@pilotiq/pilotiq 0.7.2 → 0.8.0

package/src/actions/bulkFactories.ts

@@ -0,0 +1,168 @@
+/**
+ * Bulk-placement Action factories — `bulkDelete / bulkRestore /
+ * bulkForceDelete / bulkReplicate`. Handler-style: iterate
+ * `ctx.records`, run policy per-row (parallelized via
+ * `forEachAllowed`), call the matching Resource / Model method. No new
+ * routes — the existing `/_action/:actionName` dispatcher already
+ * handles bulk via `ctx.records`.
+ *
+ * Drop into `bulkActions([...])` from inside `Resource.table()`. Each
+ * returns a notification with the count succeeded; rows whose policy
+ * denied (or whose call threw) are silently skipped — surface them
+ * via your own logging if needed. When no rows succeed (empty
+ * selection, all denied, all threw) the handler emits a `'warning'`
+ * toast instead of misleading "0 X deleted" success.
+ *
+ * See `docs/plans/action-split.md` for the split plan.
+ */
+
+import { Action, type ReplicateOptions, type ResourceLike } from './Action.js'
+import { buildReplica, callPredicate, forEachAllowed } from './factoryHelpers.js'
+
+/** Pick the right label form for a count — `labelSingular` for 1,
+ *  `label` (plural, lowercased) for any other count. Fall back to a
+ *  naive `${labelSingular}s` when no plural label is set. Used by bulk
+ *  notification copy so we don't ship "1 posts moved to trash". */
+function labelForCount(R: ResourceLike, n: number): string {
+  if (n === 1) return R.labelSingular.toLowerCase()
+  const plural = R.label?.toLowerCase()
+  return plural ?? `${R.labelSingular.toLowerCase()}s`
+}
+
+/** Bulk delete — calls `R.deleteRecord(id)` per row. On a
+ *  soft-delete resource that hits `Model.delete()` which writes
+ *  `deletedAt`. Notification: "N posts moved to trash" / "N posts
+ *  deleted" depending on `R.softDeletes`. */
+export function bulkDeleteAction(R: ResourceLike, _basePath: string): Action {
+  return Action.make('bulkDelete')
+    .label('Delete selected')
+    .destructive()
+    .bulk()
+    .confirm(`Delete the selected ${labelForCount(R, 0)}?`)
+    .handler(async (ctx) => {
+      const records = ctx.records ?? []
+      const Rfull = R as ResourceLike & { deleteRecord(id: string): Promise<void> }
+      const verb = R.softDeletes ? 'moved to trash' : 'deleted'
+      const n = await forEachAllowed(
+        records,
+        (record) => callPredicate(R.canDelete, ctx.user, record),
+        async (id) => { await Rfull.deleteRecord(id) },
+      )
+      if (n === 0) {
+        return { notify: { title: `Nothing to delete (no permitted rows)`, type: 'warning' } as never }
+      }
+      return { notify: { title: `${n} ${labelForCount(R, n)} ${verb}`, type: 'success' } as never }
+    })
+}
+
+/** Bulk restore — calls `R.model.restore(id)` per row. Visible only
+ *  on soft-delete resources (the entire bulk-restore concept is
+ *  specific to them). */
+export function bulkRestoreAction(R: ResourceLike, _basePath: string): Action {
+  return Action.make('bulkRestore')
+    .label('Restore selected')
+    .color('success')
+    .bulk()
+    .confirm(`Restore the selected ${labelForCount(R, 0)}?`)
+    .handler(async (ctx) => {
+      const Rfull = R as ResourceLike & { model?: { restore?(id: string | number): Promise<unknown> } }
+      const restore = Rfull.model?.restore
+      if (!restore) {
+        return { notify: { title: 'Restore not configured', type: 'error' } as never }
+      }
+      const records = ctx.records ?? []
+      const n = await forEachAllowed(
+        records,
+        (record) => callPredicate(R.canRestore, ctx.user, record),
+        async (id) => { await restore(id) },
+      )
+      if (n === 0) {
+        return { notify: { title: `Nothing to restore (no permitted rows)`, type: 'warning' } as never }
+      }
+      return { notify: { title: `${n} ${labelForCount(R, n)} restored`, type: 'success' } as never }
+    })
+}
+
+/** Bulk force-delete — calls `R.model.forceDelete(id)` per row. Same
+ *  destructive confirm as the per-row variant. Visible only on
+ *  soft-delete resources. */
+export function bulkForceDeleteAction(R: ResourceLike, _basePath: string): Action {
+  return Action.make('bulkForceDelete')
+    .label('Delete forever')
+    .destructive()
+    .bulk()
+    .confirm(`Permanently delete the selected ${labelForCount(R, 0)}? This cannot be undone.`)
+    .handler(async (ctx) => {
+      const Rfull = R as ResourceLike & { model?: { forceDelete?(id: string | number): Promise<void> } }
+      const forceDelete = Rfull.model?.forceDelete
+      if (!forceDelete) {
+        return { notify: { title: 'Force-delete not configured', type: 'error' } as never }
+      }
+      const records = ctx.records ?? []
+      const n = await forEachAllowed(
+        records,
+        (record) => callPredicate(R.canForceDelete, ctx.user, record),
+        async (id) => { await forceDelete(id) },
+      )
+      if (n === 0) {
+        return { notify: { title: `Nothing to delete (no permitted rows)`, type: 'warning' } as never }
+      }
+      return { notify: { title: `${n} ${labelForCount(R, n)} permanently deleted`, type: 'success' } as never }
+    })
+}
+
+/**
+ * Bulk replicate — calls `R.model.create(...)` once per selected row
+ * with the source row's attributes minus PK / soft-delete column /
+ * `opts.excludeAttributes`. Optional `opts.beforeReplicaSaved(replica,
+ * source)` runs per-row. Rows that throw during create are skipped
+ * silently so a single bad row doesn't abort the batch (the user sees
+ * the success count on the toast). Visibility delegates to
+ * `R.canCreate(user)`.
+ *
+ * Sibling of `replicateAction` — same options bag, same strip set,
+ * same authorization gate. Stays on the list page (no per-row
+ * redirect possible for N rows).
+ */
+export function bulkReplicateAction(
+  R:        ResourceLike,
+  _basePath: string,
+  opts:     ReplicateOptions = {},
+): Action {
+  return Action.make('bulkReplicate')
+    .label('Replicate selected')
+    .bulk()
+    .confirm(`Replicate the selected ${labelForCount(R, 0)}?`)
+    .handler(async (ctx) => {
+      const M = R.model
+      if (!M || typeof M.create !== 'function') {
+        return { notify: { title: 'Replicate not configured (resource has no model.create)', type: 'error' } as never }
+      }
+      const records = ctx.records ?? []
+      // Per-row predicate eval preserved — `canCreate` ignores the record
+      // in the common case, but users may write stateful predicates that
+      // gate per-attempt.
+      const n = await forEachAllowed(
+        records,
+        () => callPredicate(R.canCreate, ctx.user),
+        async (_id, source) => {
+          const { replica } = await buildReplica(source, M, {
+            excludeAttributes:  opts.excludeAttributes,
+            deletedAtColumn:    R.deletedAtColumn,
+            beforeReplicaSaved: opts.beforeReplicaSaved,
+          })
+          await M.create(replica)
+        },
+      )
+      if (n === 0) {
+        return { notify: { title: `Nothing to replicate (no permitted rows)`, type: 'warning' } as never }
+      }
+      const defaultTitle = `${n} ${labelForCount(R, n)} replicated`
+      const overrideTitle = opts.getCreatedNotificationTitle
+        ? await opts.getCreatedNotificationTitle({ count: n, records })
+        : undefined
+      const title = overrideTitle !== undefined ? overrideTitle : defaultTitle
+      return { notify: { title, type: 'success' } as never }
+    })
+    .visible(({ user }) => callPredicate(R.canCreate, user))
+}

package/src/actions/crudFactories.ts

@@ -0,0 +1,220 @@
+/**
+ * CRUD single-row Action factories — `create / edit / view / delete /
+ * replicate / restore / forceDelete`, plus the notification `markAsRead`
+ * factory.
+ *
+ * Each factory builds and returns a configured `Action`. The matching
+ * `static` methods on the `Action` class are thin delegators that call
+ * into these functions, preserving the public `Action.create(R, base)`
+ * call shape.
+ *
+ * See `docs/plans/action-split.md` for the split plan.
+ */
+
+import { Action, type ReplicateOptions, type ResourceLike } from './Action.js'
+import { buildReplica, callPredicate, isTrashed, resourceBase } from './factoryHelpers.js'
+
+/** Create-action factory — link to `${basePath}/${R.slug}/create`.
+ * Auto-hides when `R.canCreate(user)` returns false. */
+export function createAction(R: ResourceLike, basePath: string): Action {
+  return Action.make('create')
+    .label(`New ${R.labelSingular}`)
+    .href(`${resourceBase(basePath, R)}/create`)
+    .visible(({ user }) => callPredicate(R.canCreate, user))
+}
+
+/**
+ * Edit-action factory — link to the resource's edit page.
+ *
+ * Pass `recordId` when building actions for a single-record context
+ * (e.g. `ViewPage.getActions()`); the URL is baked at config time.
+ * Omit `recordId` for row context (`Table.recordActions(...)`); the
+ * URL keeps the `:id` template and the renderer substitutes per-row.
+ *
+ * Auto-hides when `R.canEdit(user, record)` returns false. For row
+ * context the per-row record threads in via `loadTableRecords`'s
+ * per-row eval; for view-page context, `resolveSchema` provides the
+ * resolved record on the eval context.
+ */
+export function editAction(R: ResourceLike, basePath: string, recordId?: string): Action {
+  const id = recordId ?? ':id'
+  return Action.make('edit')
+    .label('Edit')
+    .href(`${resourceBase(basePath, R)}/${id}/edit`)
+    .visible(({ user, record }) => callPredicate(R.canEdit, user, record))
+}
+
+/** View-action factory — link to the resource's view page. See `editAction` for the `recordId` semantics.
+ * Auto-hides when `R.canView(user, record)` returns false. */
+export function viewAction(R: ResourceLike, basePath: string, recordId?: string): Action {
+  const id = recordId ?? ':id'
+  return Action.make('view')
+    .label('View')
+    .href(`${resourceBase(basePath, R)}/${id}`)
+    .visible(({ user, record }) => callPredicate(R.canView, user, record))
+}
+
+/**
+ * Delete-action factory — POSTs to the resource's delete route,
+ * destructive style, with a confirmation prompt referencing the
+ * resource label. Same `recordId` semantics as `editAction`.
+ * Auto-hides when `R.canDelete(user, record)` returns false.
+ *
+ * Plan #13 — when `R.softDeletes = true`, additionally hides on
+ * rows whose `deletedAtColumn` is set (already-trashed rows get the
+ * Restore + ForceDelete pair instead, surfaced via the matching
+ * factories below).
+ */
+export function deleteAction(R: ResourceLike, basePath: string, recordId?: string): Action {
+  const id = recordId ?? ':id'
+  return Action.make('delete')
+    .label('Delete')
+    .destructive()
+    .method('post')
+    .action(`${resourceBase(basePath, R)}/${id}/delete`)
+    .confirm(`Delete this ${R.labelSingular.toLowerCase()}?`)
+    .visible(async ({ user, record }) => {
+      if (R.softDeletes && isTrashed(record, R)) return false
+      return callPredicate(R.canDelete, user, record)
+    })
+}
+
+/**
+ * Replicate-action factory — handler-style. Loads the source record
+ * from `ctx.record` (the `_action/:actionName` route already resolves
+ * it through `R.query(ctx)` for row + single-target placements),
+ * strips PK + soft-delete column + any `opts.excludeAttributes`,
+ * optionally runs `opts.beforeReplicaSaved`, and creates a new row
+ * via `R.model.create(...)`. Redirects to the new record's edit page
+ * on success so the user can review + tweak before saving again.
+ *
+ * `recordId` kept in the signature for parity with `delete / edit /
+ * view` so users can swap factories without rewriting call sites; the
+ * dispatcher resolves the source record from the URL and hands it to
+ * the handler as `ctx.record`, so we don't reference `recordId` here.
+ *
+ * Auto-hides when `R.canCreate(user)` returns false — replicating
+ * writes a new row, so the gate is `canCreate`, not `canView`.
+ */
+export function replicateAction(
+  R:        ResourceLike,
+  basePath: string,
+  recordId?: string,
+  opts:     ReplicateOptions = {},
+): Action {
+  void recordId
+  return Action.make('replicate')
+    .label('Replicate')
+    .handler(async (ctx) => {
+      const source = ctx.record
+      if (!source || typeof source !== 'object') {
+        return { notify: { title: 'Replicate failed: source record missing', type: 'error' } as never }
+      }
+      const M = R.model
+      if (!M || typeof M.create !== 'function') {
+        return { notify: { title: 'Replicate not configured (resource has no model.create)', type: 'error' } as never }
+      }
+
+      let replica: Record<string, unknown>
+      let pkCol: string
+      try {
+        ({ replica, pkCol } = await buildReplica(source, M, {
+          excludeAttributes: opts.excludeAttributes,
+          deletedAtColumn:   R.deletedAtColumn,
+          beforeReplicaSaved: opts.beforeReplicaSaved,
+        }))
+      } catch (err) {
+        return { notify: { title: `Replicate failed: ${err instanceof Error ? err.message : String(err)}`, type: 'error' } as never }
+      }
+
+      let created: unknown
+      try {
+        created = await M.create(replica)
+      } catch (err) {
+        return { notify: { title: `Replicate failed: ${err instanceof Error ? err.message : String(err)}`, type: 'error' } as never }
+      }
+
+      const newId = (created as Record<string, unknown> | null | undefined)?.[pkCol]
+      const defaultRedirect = newId !== undefined && newId !== null
+        ? `${resourceBase(basePath, R)}/${String(newId)}/edit`
+        : `${resourceBase(basePath, R)}`
+      // `!== undefined` rather than `??` so an override returning
+      // `null`/empty-string isn't silently swallowed (see
+      // feedback_nullish_swallows_explicit_null).
+      const overrideRedirect = opts.getRedirectUrl
+        ? await opts.getRedirectUrl({ replica: created, source })
+        : undefined
+      const redirect = overrideRedirect !== undefined ? overrideRedirect : defaultRedirect
+      const overrideTitle = opts.getCreatedNotificationTitle
+        ? await opts.getCreatedNotificationTitle({ replica: created, source })
+        : undefined
+      const title = overrideTitle !== undefined ? overrideTitle : `${R.labelSingular} replicated`
+      return {
+        redirect,
+        notify: { title, type: 'success' } as never,
+      }
+    })
+    .visible(({ user }) => callPredicate(R.canCreate, user))
+}
+
+/**
+ * Plan #13 — Restore factory. POSTs to the resource's restore route,
+ * success-styled, no confirm prompt (restoration is reversible).
+ * Auto-hides on live (non-trashed) rows AND when `R.canRestore(user,
+ * record)` returns false. Same `recordId` semantics as `editAction`.
+ */
+export function restoreAction(R: ResourceLike, basePath: string, recordId?: string): Action {
+  const id = recordId ?? ':id'
+  return Action.make('restore')
+    .label('Restore')
+    .color('success')
+    .method('post')
+    .action(`${resourceBase(basePath, R)}/${id}/restore`)
+    .visible(async ({ user, record }) => {
+      if (!isTrashed(record, R)) return false
+      return callPredicate(R.canRestore, user, record)
+    })
+}
+
+/**
+ * Plan #13 — Force-delete factory. POSTs to the resource's
+ * force-delete route, destructive-styled, with a stricter confirm
+ * prompt referencing permanence. Auto-hides on live (non-trashed)
+ * rows AND when `R.canForceDelete(user, record)` returns false.
+ */
+export function forceDeleteAction(R: ResourceLike, basePath: string, recordId?: string): Action {
+  const id = recordId ?? ':id'
+  return Action.make('forceDelete')
+    .label('Delete forever')
+    .destructive()
+    .method('post')
+    .action(`${resourceBase(basePath, R)}/${id}/force-delete`)
+    .confirm(`Permanently delete this ${R.labelSingular.toLowerCase()}? This cannot be undone.`)
+    .visible(async ({ user, record }) => {
+      if (!isTrashed(record, R)) return false
+      return callPredicate(R.canForceDelete, user, record)
+    })
+}
+
+/**
+ * Mark-as-read factory — POSTs to the panel's notification read
+ * endpoint for the given notification id. The endpoint
+ * (`${base}/_notifications/:id/read`) is mounted by
+ * `Pilotiq.databaseNotifications()`, so calling this without
+ * opting into the bell surface produces an Action whose POST 404s.
+ *
+ * `notificationId` is baked at config time. For row context where
+ * the id varies per row, omit it and the URL keeps the `:id`
+ * template; the renderer substitutes per-row at render time
+ * (parallel to `editAction`'s row form).
+ *
+ * No auto-visibility. Wrap in `.visible(({ record }) => !record.readAt)`
+ * to hide on already-read rows.
+ */
+export function markAsReadAction(basePath: string, notificationId?: string): Action {
+  const id = notificationId ?? ':id'
+  return Action.make('markAsRead')
+    .label('Mark as read')
+    .method('post')
+    .action(`${basePath}/_notifications/${id}/read`)
+}

package/src/actions/factoryHelpers.ts

@@ -0,0 +1,177 @@
+/**
+ * Shared helpers for the Action factory modules — `crudFactories.ts`,
+ * `bulkFactories.ts`, `relationFactories.ts`, `m2mFactories.ts`.
+ *
+ * Lives in its own file so the per-phase factory modules stay focused
+ * on their own factory bodies. Anything consumed by 2+ phase files
+ * lands here; phase-local helpers stay alongside their phase's
+ * factories.
+ *
+ * See `docs/plans/action-split.md` for the split plan.
+ */
+
+import type { ResourceLike } from './Action.js'
+import type { RelationManagerContext } from '../RelationManager.js'
+
+/** Cluster-aware resource base path. Mirrors `clusterPaths.resourceBasePath`
+ *  but uses the structural `ResourceLike` shape so `Action.ts` stays
+ *  cycle-free against `Resource.ts`. */
+export function resourceBase(basePath: string, R: ResourceLike): string {
+  if (R.cluster) return `${basePath}/${R.cluster.getSlug()}/${R.getSlug()}`
+  return `${basePath}/${R.getSlug()}`
+}
+
+/** Call a (possibly undefined) Resource predicate. When unset, the
+ * predicate is treated as "allowed" (returns true) so the factory
+ * doesn't hide actions on Resources that haven't opted into Plan #10. */
+export function callPredicate(
+  fn: ((user: unknown, record?: unknown) => boolean | Promise<boolean>) | undefined,
+  user: unknown,
+  record?: unknown,
+): boolean | Promise<boolean> {
+  if (!fn) return true
+  return fn(user, record)
+}
+
+/** Read `record[R.deletedAtColumn ?? 'deletedAt']` and return true when
+ *  the row is currently trashed (soft-deleted). Permissive on shape —
+ *  bare `null` / `undefined` count as live; any other truthy value is
+ *  trashed. */
+export function isTrashed(record: unknown, R: ResourceLike): boolean {
+  if (!record || typeof record !== 'object') return false
+  const col = R.deletedAtColumn ?? 'deletedAt'
+  const v = (record as Record<string, unknown>)[col]
+  return v !== null && v !== undefined
+}
+
+/** True when a `RelationManagerContext.mode` denotes a pivot-mutation
+ *  shape — i.e. a many-to-many relation. All three modes share the
+ *  `attach` / `detach` / `sync` accessor surface (the rudder ORM stamps
+ *  + filters the polymorphic discriminator transparently for the morph
+ *  variants). The `relationCreate / Edit / Delete` factories auto-hide
+ *  under any of these modes because per-pivot-row create / edit / delete
+ *  is meaningless — users create the related record via its own Resource,
+ *  then attach via `relationAttach`. */
+export function isM2MMode(mode: RelationManagerContext['mode']): boolean {
+  return mode === 'belongsToMany' || mode === 'morphToMany' || mode === 'morphedByMany'
+}
+
+/**
+ * Build the URL prefix for a relation factory action. Without
+ * a `chain` (depth-1 manager), this is the familiar
+ * `${base}/${parentSlug}/${parentId}/${relationship}`. With a chain
+ * (depth-2 nested manager), it threads the outer record + relationship
+ * between the parent slug and the leaf parent id:
+ *
+ *   `${base}/${parentSlug}/${chain[0].recordId}/${chain[0].relationship}/${parentId}/${relationship}`
+ *
+ * Pure; takes a `RelationManagerContext` and emits a string. The leaf
+ * record id (and trailing `/edit`, `/delete`, etc.) gets appended by
+ * the caller.
+ */
+export function relationUrlPrefix(ctx: RelationManagerContext): string {
+  const head = `${ctx.basePath}/${ctx.parentSlug}`
+  const chain = ctx.chain ?? []
+  let mid = ''
+  for (const step of chain) {
+    mid += `/${step.recordId}/${step.relationship}`
+  }
+  return `${head}${mid}/${ctx.parentId}/${ctx.relationship}`
+}
+
+/** Options bag for `buildReplica`. Optional fields explicitly accept
+ *  `undefined` so call sites can pass `opts.excludeAttributes` through
+ *  unconditionally under `exactOptionalPropertyTypes: true`. */
+export interface BuildReplicaOptions {
+  /** Attribute keys to drop from the replicated payload IN ADDITION TO
+   *  the model's primary key and soft-delete column. */
+  excludeAttributes?: readonly string[] | undefined
+  /** Soft-delete column name on the source Resource. Defaults to
+   *  `'deletedAt'`. Read separately from the model because the column
+   *  lives on the Resource shape (`R.deletedAtColumn`) rather than on
+   *  the model itself. */
+  deletedAtColumn?: string | undefined
+  /** Force-pinned columns applied AFTER the strip and BEFORE the user
+   *  `beforeReplicaSaved` mutator. Used by the relation replicate
+   *  factories to re-stamp the parent attachment FK / morph columns
+   *  so a tampered source row can't slip a different parent in. */
+  pin?: Record<string, unknown> | undefined
+  /** Optional user mutator. Runs after the strip + pin. */
+  beforeReplicaSaved?: ((
+    replica: Record<string, unknown>,
+    source:  unknown,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>) | undefined
+}
+
+/**
+ * Build a replica payload from a source record. Used by every replicate
+ * factory (`replicateAction / bulkReplicateAction / relationReplicateAction
+ * / relationBulkReplicateAction`).
+ *
+ * Strips the model's primary key (`model.primaryKey`, defaulting to
+ * `'id'`), the soft-delete column (defaulting to `'deletedAt'`), and any
+ * `excludeAttributes` keys. Applies `pin` columns (parent attachment
+ * for relation factories), then runs the optional `beforeReplicaSaved`
+ * user mutator. Returns the replica AND the resolved primary-key column
+ * name (callers need it to read `created[pkCol]` for redirect URLs).
+ *
+ * Does NOT call `model.create` — callers wrap their own create + error
+ * handling around the returned replica.
+ */
+export async function buildReplica(
+  source: unknown,
+  model:  { primaryKey?: string },
+  opts:   BuildReplicaOptions = {},
+): Promise<{ replica: Record<string, unknown>; pkCol: string }> {
+  const pkCol      = model.primaryKey ?? 'id'
+  const trashedCol = opts.deletedAtColumn ?? 'deletedAt'
+  const skip       = new Set<string>([pkCol, trashedCol, ...(opts.excludeAttributes ?? [])])
+  let replica: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(source as Record<string, unknown>)) {
+    if (skip.has(k)) continue
+    replica[k] = v
+  }
+  if (opts.pin) Object.assign(replica, opts.pin)
+  if (opts.beforeReplicaSaved) {
+    replica = await opts.beforeReplicaSaved(replica, source)
+  }
+  return { replica, pkCol }
+}
+
+/**
+ * Iterate `records`, run the policy probe in parallel up-front (only
+ * allowed rows enter the serial work loop), call `op(id, record)` per
+ * allowed row, swallow per-row throws (the aggregate notification shows
+ * the count succeeded). Returns the success count.
+ *
+ * Used by every bulk handler (`bulkDeleteAction / bulkRestoreAction /
+ * bulkForceDeleteAction / bulkReplicateAction / relationBulkReplicateAction
+ * / relationBulkDetachAction`-style pattern).
+ *
+ * Rows whose `record.id` coerces to an empty string are skipped without
+ * counting them as an attempt. The policy probe runs via `Promise.all`
+ * so backend round-trips parallelize, but the write loop stays serial
+ * (no transaction in v1 — concurrent writes would muddy failure
+ * semantics).
+ */
+export async function forEachAllowed(
+  records:   readonly unknown[],
+  isAllowed: (record: unknown, index: number) => boolean | Promise<boolean>,
+  op:        (id: string, record: unknown, index: number) => Promise<void>,
+): Promise<number> {
+  const allowedFlags = await Promise.all(
+    records.map((r, i) => isAllowed(r, i)),
+  )
+  let n = 0
+  for (let i = 0; i < records.length; i++) {
+    if (!allowedFlags[i]) continue
+    const record = records[i]
+    const id = String((record as { id?: unknown } | null | undefined)?.id ?? '')
+    if (!id) continue
+    try {
+      await op(id, record, i)
+      n++
+    } catch { /* skip — agg notify shows total */ }
+  }
+  return n
+}