@pilotiq/pilotiq 0.21.0 → 0.22.0

package/src/actions/importFactory.ts

@@ -65,6 +65,11 @@ export interface ImportOptions {
    *  exceeded — protects against accidental million-row uploads. Default
    *  `10_000`. */
   maxRows?: number
+  /** Number of rows to process in parallel. The importer chunks the row
+   *  list into batches of this size and runs each chunk via `Promise.all`.
+   *  Order within a chunk is non-deterministic; row indices in error
+   *  messages still match the original CSV/JSON position. Default `10`. */
+  concurrency?: number
   /** Final hook after the import loop. Useful for audit-log writes,
    *  cache invalidation, etc. Async-aware. */
   onComplete?: (summary: ImportSummary, ctx: ImportContext) => void | Promise<void>
@@ -123,16 +128,21 @@ export async function runImport(
 ): Promise<ImportSummary> {
   const summary: ImportSummary = { created: 0, updated: 0, skipped: 0, errors: [] }
   const upsertBy = opts.upsertBy
+  const concurrency = Math.max(1, opts.concurrency ?? 10)
 
-  for (let i = 0; i < rows.length; i++) {
-    const row = rows[i]!
+  // Per-row outcome — a small value type so chunks can resolve in any
+  // order and we still accumulate `summary` in original-row order.
+  type RowOutcome =
+    | { kind: 'created' }
+    | { kind: 'updated' }
+    | { kind: 'skipped'; row: number; message: string }
+
+  async function processRow(row: Record<string, unknown>, i: number): Promise<RowOutcome> {
     const rowCtx: ImportContext = { ...ctx, rowIndex: i }
     try {
       const guard = await opts.validate?.(row, rowCtx)
       if (typeof guard === 'string' && guard.length > 0) {
-        summary.skipped++
-        summary.errors.push({ row: i + 1, message: guard })
-        continue
+        return { kind: 'skipped', row: i + 1, message: guard }
       }
 
       if (mode === 'upsert' && upsertBy) {
@@ -144,8 +154,7 @@ export async function runImport(
             ? await opts.beforeUpdate(row, existing, rowCtx)
             : row
           await M.update(id, payload)
-          summary.updated++
-          continue
+          return { kind: 'updated' }
         }
       }
 
@@ -153,10 +162,22 @@ export async function runImport(
         ? await opts.beforeCreate(row, rowCtx)
         : row
       await M.create(payload)
-      summary.created++
+      return { kind: 'created' }
     } catch (err) {
-      summary.skipped++
-      summary.errors.push({ row: i + 1, message: err instanceof Error ? err.message : 'unknown' })
+      return { kind: 'skipped', row: i + 1, message: err instanceof Error ? err.message : 'unknown' }
+    }
+  }
+
+  for (let start = 0; start < rows.length; start += concurrency) {
+    const slice = rows.slice(start, start + concurrency)
+    const outcomes = await Promise.all(slice.map((row, idx) => processRow(row, start + idx)))
+    for (const outcome of outcomes) {
+      if (outcome.kind === 'created')      summary.created++
+      else if (outcome.kind === 'updated') summary.updated++
+      else {
+        summary.skipped++
+        summary.errors.push({ row: outcome.row, message: outcome.message })
+      }
     }
   }
 

package/src/orm/modelDefaults.ts

@@ -50,6 +50,16 @@ export interface ModelQuery {
   orderBy(column: string, direction?: 'ASC' | 'DESC'): ModelQuery
   paginate(page: number, perPage?: number): Promise<{ data: unknown[]; total: number }>
 
+  /**
+   * Single-row `LIMIT 1` SELECT — Laravel-parity sibling of `paginate`
+   * for the "first matching row" case. Optional on the structural shape;
+   * the `@rudderjs/orm` `QueryBuilder` ships it, test stubs typically
+   * don't. Callers that need it should fall back to
+   * `(await q.paginate(1, 1)).data[0]` when absent — see `findRecord` /
+   * `loadSingularRecord` / `childBelongsToParent` for the pattern.
+   */
+  first?(): Promise<unknown | null>
+
   /**
    * Plan #13 — soft-delete query scopes. Optional on the structural
    * shape; the `@rudderjs/orm-prisma` QueryBuilder ships them when
@@ -192,7 +202,7 @@ export function modelLoadRecord(R: ResourceLike): LoadRecordHandler {
  * `Global` subclasses with `static model = M` set get this wired
  * automatically by `defaultGlobalEditPage`.
  *
- * Default strategy: paginate(1, 1) — i.e. "the first row". Pass
+ * Default strategy: `.first()` — i.e. the first matching row. Pass
  * `findSingular` to switch to a fixed-id lookup
  * (`(q) => q.where('id', '=', 1)`) or a slug-style lookup
  * (`(q) => q.where('key', '=', 'site')`).
@@ -208,6 +218,7 @@ export function loadSingularRecord(
   return async (): Promise<unknown> => {
     let q = M.query()
     if (opts?.findSingular) q = opts.findSingular(q)
+    if (q.first) return (await q.first()) ?? null
     const result = await q.paginate(1, 1)
     const data = (result?.data ?? []) as unknown[]
     return data[0] ?? null
@@ -234,7 +245,9 @@ export async function findRecord<T = unknown>(
   const M = R.model
   if (!M) return undefined
   const pk = getPrimaryKey(M)
-  const result = await R.query(ctx).where(pk, '=', id).paginate(1, 1)
+  const q = R.query(ctx).where(pk, '=', id)
+  if (q.first) return ((await q.first()) ?? undefined) as T | undefined
+  const result = await q.paginate(1, 1)
   const data = (result?.data ?? []) as unknown[]
   return data[0] as T | undefined
 }

package/src/pageData/forms.ts

@@ -58,7 +58,7 @@ async function resolveScopeForm(
   let baseCtxExtras: Record<string, unknown> = {}
 
   if (scope.kind === 'resource-create' || scope.kind === 'resource-edit') {
-    const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+    const R = pilotiq.findResource(scope.slug)
     if (!R) return null
     const pages = R.resolvePages()
     if (scope.kind === 'resource-create') {
@@ -77,14 +77,14 @@ async function resolveScopeForm(
       }
     }
   } else if (scope.kind === 'global-edit') {
-    const G = cfg.globals.find(g => g.getSlug() === scope.slug)
+    const G = pilotiq.findGlobal(scope.slug)
     if (!G) return null
     const pages = G.resolvePages()
     if (!pages.edit) return null
     PageClass = pages.edit
     mode = 'edit'
   } else {
-    const P = cfg.pages.find(p => p.getSlug() === scope.pageSlug)
+    const P = pilotiq.findPage(scope.pageSlug)
     if (!P) return null
     PageClass = P
     // Custom pages don't have a record/edit-mode concept — pass mode

package/src/pageData/misc.ts

@@ -43,7 +43,7 @@ export async function globalEditData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const G = cfg.globals.find(g => g.getSlug() === slug)
+  const G = pilotiq.findGlobal(slug)
   if (!G) return null
   const pages = G.resolvePages()
   if (!pages.edit) return null
@@ -98,7 +98,7 @@ export async function globalViewData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const G = cfg.globals.find(g => g.getSlug() === slug)
+  const G = pilotiq.findGlobal(slug)
   if (!G) return null
   const pages = G.resolvePages()
   if (!pages.view) return null
@@ -134,7 +134,7 @@ export async function customPageData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const PageClass = cfg.pages.find(P => P.getSlug() === pageSlug)
+  const PageClass = pilotiq.findPage(pageSlug)
   if (!PageClass) return null
 
   const pageUrl = pageBasePath(cfg.path, PageClass)
@@ -237,14 +237,14 @@ export async function widgetData(
     ctx = uploadCtx(userCtx({ basePath: cfg.path }, user), cfg)
     elements = await callPageSchema(cfg.dashboardPage, ctx)
   } else if (scope.kind === 'page') {
-    const P = cfg.pages.find(p => p.getSlug() === scope.pageSlug)
+    const P = pilotiq.findPage(scope.pageSlug)
     if (!P) return { ok: false, status: 404, error: 'Page not found' }
     ctx = uploadCtx(userCtx({ basePath: cfg.path }, user), cfg)
     elements = await callPageSchema(P, ctx)
   } else {
     // Resource-scope: re-resolve the list page's schema so widgets from
     // `Resource.headerSchema()` / `footerSchema()` are reachable.
-    const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+    const R = pilotiq.findResource(scope.slug)
     if (!R) return { ok: false, status: 404, error: 'Resource not found' }
     const pages = R.resolvePages()
     if (!pages.index) return { ok: false, status: 404, error: 'Resource has no list page' }

package/src/pageData/navigation.ts

@@ -627,7 +627,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
   const raw: RawNavItem[] = []
   let idx = 0
 
-  const pushBadge: Array<{ item: RawNavItem; handler: () => unknown }> = []
+  const pushBadge: Array<{ item: RawNavItem; handler: () => unknown; owner: string }> = []
 
   // Plan #10 — pre-evaluate canAccess for every owner in parallel so we
   // can drop forbidden items before flattening. Failed predicates fail
@@ -672,7 +672,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (R.cluster)                              item.parent       = R.cluster.name
     else if (R.navigationParentItem !== undefined) item.parent    = R.navigationParentItem
     if (R.navigationBadgeColor   !== 'default') item.badgeColor   = R.navigationBadgeColor
-    if (R.navigationBadge)                       pushBadge.push({ item, handler: R.navigationBadge })
+    if (R.navigationBadge)                       pushBadge.push({ item, handler: R.navigationBadge, owner: R.name })
     raw.push(item)
   }
 
@@ -697,7 +697,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (G.cluster)                              item.parent       = G.cluster.name
     else if (G.navigationParentItem !== undefined) item.parent    = G.navigationParentItem
     if (G.navigationBadgeColor   !== 'default') item.badgeColor   = G.navigationBadgeColor
-    if (G.navigationBadge)                       pushBadge.push({ item, handler: G.navigationBadge })
+    if (G.navigationBadge)                       pushBadge.push({ item, handler: G.navigationBadge, owner: G.name })
     raw.push(item)
   }
 
@@ -724,7 +724,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (P.cluster && !isDashboard)              item.parent       = P.cluster.name
     else if (P.navigationParentItem !== undefined) item.parent    = P.navigationParentItem
     if (P.navigationBadgeColor   !== 'default') item.badgeColor   = P.navigationBadgeColor
-    if (P.navigationBadge)                       pushBadge.push({ item, handler: P.navigationBadge })
+    if (P.navigationBadge)                       pushBadge.push({ item, handler: P.navigationBadge, owner: P.name })
     raw.push(item)
   }
 
@@ -755,15 +755,17 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (C.navigationSort         !== undefined) item.sort         = C.navigationSort
     if (C.navigationParentItem   !== undefined) item.parent       = C.navigationParentItem
     if (C.navigationBadgeColor   !== 'default') item.badgeColor   = C.navigationBadgeColor
-    if (C.navigationBadge)                       pushBadge.push({ item, handler: C.navigationBadge })
+    if (C.navigationBadge)                       pushBadge.push({ item, handler: C.navigationBadge, owner: C.name })
     raw.push(item)
   }
 
-  await Promise.all(pushBadge.map(async ({ item, handler }) => {
+  await Promise.all(pushBadge.map(async ({ item, handler, owner }) => {
     try {
-      const v = await handler()
-      if (v === undefined || v === null) return
-      item.badge = String(v)
+      const v = await pilotiq.resolveNavigationBadge(owner, user, async () => {
+        const raw = await handler()
+        return raw === undefined || raw === null ? undefined : String(raw)
+      })
+      if (v !== undefined) item.badge = v
     } catch {
       // Per-badge errors stay silent.
     }

package/src/pageData/relationPages.ts

@@ -193,7 +193,9 @@ async function childBelongsToParent(
     const q: ModelQuery = (parentModel.relatedQuery
       ? parentModel.relatedQuery(parent, relationship)
       : (parent as { related: (n: string) => ModelQuery }).related(relationship))
-    const result = await q.where(childPk, '=', childId).paginate(1, 1)
+      .where(childPk, '=', childId)
+    if (q.first) return (await q.first()) !== null
+    const result = await q.paginate(1, 1)
     return result.total > 0
   } catch {
     return false
@@ -294,7 +296,7 @@ export async function relationManagerData(
 
   const cfg = pilotiq.getConfig()
 
-  const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+  const R = pilotiq.findResource(scope.slug)
   if (!R) return null
 
   const M = findManager(R, scope.relationship)
@@ -769,7 +771,7 @@ export async function resolveRelationChain(
 ): Promise<ResolvedChain | { ok: false; status: 403 } | null> {
   const cfg = pilotiq.getConfig()
 
-  const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+  const R = pilotiq.findResource(scope.slug)
   if (!R) return null
 
   // Layer 0 — same gates as the depth-1 pipeline.

package/src/pageData/resourcePages.ts

@@ -142,7 +142,7 @@ export async function resourceIndexData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
 
   const pages = R.resolvePages()
@@ -193,7 +193,7 @@ export async function resourceTableData(
   req?:    unknown,
 ): Promise<{ tables: Record<string, unknown>[] } | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
 
   const pages = R.resolvePages()
@@ -321,7 +321,7 @@ export async function resourceCreateData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const pages = R.resolvePages()
   if (!pages.create) return null
@@ -373,7 +373,7 @@ export async function resourceEditData(
   req?:     unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const pages = R.resolvePages()
   if (!pages.edit) return null
@@ -466,7 +466,7 @@ export async function resourceViewData(
   req?:     unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const pages = R.resolvePages()
   if (!pages.view) return null
@@ -538,7 +538,7 @@ export async function resourceRecordPageData(
   req?:          unknown,
 ): Promise<Record<string, unknown> | null | { ok: false; status: 403 }> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const recordPages = R.getRecordPages()
   const PageClass = recordPages[subPageSlug]

package/src/plugins/index.ts

@@ -1 +1,8 @@
 export { themeEditor } from './themeEditor.js'
+export type { ThemeEditorOptions } from './themeEditor.js'
+export { prismaThemeStorage } from '../theme/storage.js'
+export type {
+  ThemeStorageAdapter,
+  PanelGlobalDelegate,
+  PrismaThemeStorageOptions,
+} from '../theme/storage.js'

package/src/plugins/themeEditor.test.ts

@@ -0,0 +1,36 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { Pilotiq } from '../Pilotiq.js'
+import { themeEditor } from './themeEditor.js'
+import type { ThemeStorageAdapter } from '../theme/storage.js'
+
+function makeStubAdapter(): ThemeStorageAdapter {
+  return {
+    async load() { return null },
+    async save() { /* noop */ },
+    async clear() { /* noop */ },
+  }
+}
+
+describe('themeEditor() plugin', () => {
+  it('bare themeEditor() leaves the storage slot undefined (boot resolves it)', () => {
+    const panel = Pilotiq.make('admin').use(themeEditor())
+    assert.equal(panel.getConfig().themeEditor, true)
+    assert.equal(panel.getThemeStorage(), undefined)
+  })
+
+  it('themeEditor({ storage }) stamps the adapter onto the panel', () => {
+    const adapter = makeStubAdapter()
+    const panel = Pilotiq.make('admin').use(themeEditor({ storage: adapter }))
+    assert.equal(panel.getThemeStorage(), adapter)
+  })
+
+  it('themeEditor() can be called on multiple panels without leaking adapters', () => {
+    const a = makeStubAdapter()
+    const b = makeStubAdapter()
+    const panelA = Pilotiq.make('admin').use(themeEditor({ storage: a }))
+    const panelB = Pilotiq.make('billing').use(themeEditor({ storage: b }))
+    assert.equal(panelA.getThemeStorage(), a)
+    assert.equal(panelB.getThemeStorage(), b)
+  })
+})

package/src/plugins/themeEditor.ts

@@ -1,4 +1,24 @@
 import type { PilotiqPlugin } from '../Pilotiq.js'
+import type { ThemeStorageAdapter } from '../theme/storage.js'
+
+export interface ThemeEditorOptions {
+  /**
+   * Override persistence adapter. Defaults to the implicit Prisma
+   * fallback (auto-resolved from `app.make('prisma')` against the
+   * `panelGlobal` row) — that fallback is deprecated; pass an explicit
+   * adapter to opt out and silence the deprecation warning.
+   *
+   * @example
+   * ```ts
+   * import { prismaThemeStorage, themeEditor } from '@pilotiq/pilotiq/plugins'
+   *
+   * .use(themeEditor({
+   *   storage: prismaThemeStorage(prisma, { slug: 'admin__theme' }),
+   * }))
+   * ```
+   */
+  storage?: ThemeStorageAdapter
+}
 
 /**
  * Theme editor plugin — adds an interactive theme customization page
@@ -14,11 +34,12 @@ import type { PilotiqPlugin } from '../Pilotiq.js'
  *   .use(themeEditor())
  * ```
  */
-export function themeEditor(): PilotiqPlugin {
+export function themeEditor(opts: ThemeEditorOptions = {}): PilotiqPlugin {
   return {
     name: 'theme-editor',
     register(panel) {
       panel.enableThemeEditor()
+      if (opts.storage) panel._setThemeStorage(opts.storage)
     },
   }
 }

package/src/react/CollabRoomContext.ts

@@ -22,6 +22,18 @@ export interface CollabRoom {
   ydoc:      unknown
   /** `WebsocketProvider` instance. Opaque to pilotiq core. */
   provider:  unknown
+  /**
+   * Resolves on the provider's first sync. Present when the room is
+   * wired through `@rudderjs/sync/react`'s `CollabRoomManager` (which is
+   * what `@pilotiq-pro/collab@>=0.2`'s `<RecordCollabRoom>` does);
+   * absent for legacy / hand-rolled providers. `useCollabSeed` gates
+   * its seed callback on this Promise — adapters that need a
+   * "fragment-empty?" check after first sync should consume the hook
+   * rather than calling `onProviderSynced` themselves.
+   */
+  synced?:   Promise<void>
+  /** IndexedDB persistence handle, when the room wraps `y-indexeddb`. Opaque. */
+  persistence?: unknown
   /** Presence info for cursors / avatars. Forwarded to the extension factory. */
   user?: {
     name?:  string

package/src/react/index.ts

@@ -39,6 +39,7 @@ export {
   type CollabRoom,
   type SyncedProviderLike,
 } from './CollabRoomContext.js'
+export { useCollabSeed } from './useCollabSeed.js'
 export {
   registerCollabExtensions,
   getCollabExtensions,

package/src/react/useCollabSeed.ts

@@ -0,0 +1,73 @@
+import { useEffect, useRef, useState } from 'react'
+import type { CollabRoom } from './CollabRoomContext.js'
+
+const SEED_ORIGIN = 'pilotiq-collab-seed'
+
+/**
+ * Run `seedFn` exactly once after the collab room's first sync.
+ *
+ * Mirrors `@rudderjs/sync/react`'s `useCollabSeed` shape — same purpose,
+ * reimplemented here so pilotiq core stays free of any hard runtime dep
+ * on Yjs. The `room` parameter is pilotiq's opaque `CollabRoom`, so the
+ * seed callback receives `doc: unknown` and is responsible for its own
+ * share-type lookup (`doc.getXmlFragment(key)` for Tiptap consumers,
+ * `doc.getText(key)` for CodeMirror, etc.) and its own emptiness check.
+ *
+ * Returns `true` once the seed callback has run (or was skipped because
+ * the room has no `.synced` Promise — i.e. a legacy non-framework
+ * provider), so consumers can gate editor mount / placeholder swap.
+ *
+ * The hook wraps `seedFn` in `doc.transact(..., 'pilotiq-collab-seed')`
+ * so downstream observers can filter the synthetic write. Two peers
+ * mounting against a brand-new record may both see "empty" and both
+ * seed — same race window as the legacy `onProviderSynced` path; the
+ * fix is server-side seed handoff, deferred.
+ */
+export function useCollabSeed(
+  room:    CollabRoom | null,
+  key:     string,
+  seedFn:  (doc: unknown) => void,
+): boolean {
+  const [seeded, setSeeded] = useState(false)
+  const seedFnRef = useRef(seedFn)
+  seedFnRef.current = seedFn
+
+  useEffect(() => {
+    if (!room) {
+      setSeeded(false)
+      return
+    }
+    // Legacy rooms without `.synced` — the room owner is on the hook
+    // for whatever first-sync gating they used to do via
+    // `onProviderSynced`. Mark seeded immediately so the consumer
+    // can mount without a placeholder. No seedFn runs.
+    const syncedPromise = room.synced
+    if (!syncedPromise) {
+      setSeeded(true)
+      return
+    }
+
+    let cancelled = false
+    syncedPromise.then(() => {
+      if (cancelled) return
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ydoc = room.ydoc as any
+        if (ydoc && typeof ydoc.transact === 'function') {
+          ydoc.transact(() => seedFnRef.current(ydoc), SEED_ORIGIN)
+        } else {
+          seedFnRef.current(ydoc)
+        }
+      } catch { /* ignore — seed is best-effort */ }
+      setSeeded(true)
+    }).catch(() => {
+      // synced rejects when the room is torn down before first sync.
+      // Don't surface as a seed failure — the room is gone.
+      if (!cancelled) setSeeded(false)
+    })
+
+    return () => { cancelled = true }
+  }, [room, key])
+
+  return seeded
+}

package/src/routes/globals.ts

@@ -15,8 +15,7 @@ import {
   normalizeRedirect,
   splitMeta,
   forbidden,
-  checkPolicy,
-  policyAccess,
+  policyGate,
   handleFormState,
   handleFormWizard,
   handleFormCreateOption,
@@ -49,8 +48,7 @@ export function registerGlobalRoutes(
     // POST ${editUrl}/_form/:formId/state
     router.post(`${editUrl}/_form/:formId/state`, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, true)
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, true)
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, true)
       const formId = req.params['formId']!
       return handleFormState(req, res, pilotiq, { kind: 'global-edit', slug }, formId)
     })
@@ -58,8 +56,7 @@ export function registerGlobalRoutes(
     // Plan #8 wizard step-validate endpoint for the global's edit form.
     router.post(`${editUrl}/_form/:formId/wizard`, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, true)
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, true)
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, true)
       const formId = req.params['formId']!
       return handleFormWizard(req, res, pilotiq, { kind: 'global-edit', slug }, formId)
     })
@@ -67,8 +64,7 @@ export function registerGlobalRoutes(
     // Async-mention endpoint for the global's edit form.
     router.post(`${editUrl}/_form/:formId/mentions`, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, true)
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, true)
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, true)
       const formId = req.params['formId']!
       return handleFormMentions(req, res, pilotiq, { kind: 'global-edit', slug }, formId)
     })
@@ -76,8 +72,7 @@ export function registerGlobalRoutes(
     // SelectField inline-create modal endpoint for the global's edit form.
     router.post(`${editUrl}/_form/:formId/create-option/:fieldName`, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, true)
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, true)
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, true)
       const formId    = req.params['formId']!
       const fieldName = req.params['fieldName']!
       return handleFormCreateOption(req, res, pilotiq, { kind: 'global-edit', slug }, formId, fieldName)
@@ -85,11 +80,10 @@ export function registerGlobalRoutes(
 
     router.get(editUrl, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, wantsJson(req))
       // Globals carry their record on the singleton form's `loadRecord`;
       // we don't pre-load here — pass a stub so canEdit's signature is
       // honored, and let user code decide whether to consult it.
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, wantsJson(req))
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, wantsJson(req))
       const data = await globalEditData(pilotiq, slug, undefined, req)
       return view('pilotiq.slug', data ?? {})
     })
@@ -100,8 +94,7 @@ export function registerGlobalRoutes(
       const json = wantsJson(req)
 
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, json)
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, json)
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, json)
 
       const ctx: SchemaContext = { mode: 'edit', basePath: base, ...(user !== null ? { user: user as NonNullable<SchemaContext['user']> } : {}) }
       const elements = await callPageSchema(PageClass, ctx)
@@ -147,8 +140,7 @@ export function registerGlobalRoutes(
   if (pages.view) {
     router.get(`${editUrl}/view`, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, wantsJson(req))
-      if (!await checkPolicy(() => G.canView(user, undefined))) return forbidden(res, wantsJson(req))
+      if (!await policyGate(G, user, () => G.canView(user, undefined))) return forbidden(res, wantsJson(req))
       const data = await globalViewData(pilotiq, slug, req)
       return view('pilotiq.resource-view', data ?? {})
     })