Batch Plugin - Define-once

[robnewton]

What

Adds the definition-first batch job API designed with Rob (2026-07-20 design thread), keeping the standard event-module format — no new module shape, no per-service store plumbing.

• batchJob({ triggerType, input? }) — one definition holds the trigger_type string and an optional input codec (zod-compatible parse, no zod dependency) and derives the two standard slots:
  • detector — INSERT of that trigger_type on batch_jobs, plus the UPDATE→pending replay path
  • input — a job() input mapper that parses the row's input jsonb so the job's ctx.input is typed and validated
• createBatchJob(executor, def, input, opts?) — the sanctioned write path. Validates through the same codec before any write, stamps the trigger_type, inserts status: 'pending', and reproduces the legacy dedup semantics (delay_key = triggerType-uniqueKey with on_conflict — a live collision inserts nothing and reports deduped: true). Verified byte-for-byte against a real prod ar row.
• batch({ executor }) — builds the canonical batch_jobs GraphQL store (executorBatchJobStore: update / enqueueDelayed / markStranded) from any mutate-capable executor (structurally sdk-core's GqlExecutor; documents ship pre-printed via __text, so no graphql dependency). store: stays supported for tests/portability. markStranded anticipates feat(batch): opt-in safety net for stranded pending rows #37's safety net.
• batchJobsActionHandler({ executor, batchjobs, passphrase? }) — Netlify 2.0 handler for a Hasura action createBatchjob(trigger_type, input). Refuses trigger_types outside the service's own definitions and runs the same codec, so the GraphQL surface can't create jobs the service doesn't handle.

Why

One definition per batch job means the trigger_type string exists in exactly one place per service, inserts are validated by the same codec that types the handler, and "you can only create what you handle" is literal. This is the eventkit half of the distributed batchjobs design (per-service listeners + manifest-declared subscriptions + registry-routed events-proxy); routing itself stays a monorepo tooling concern and is deliberately absent here.

Tests / docs

• 20 new tests (src/plugins/__tests__/batch-job.test.ts): detector matrix incl. replay path, codec validation at both seams, dedup semantics, canonical store lifecycle through a real kit, action handler auth/refusal/validation.
• Full suite 332/332; api-surface snapshot updated intentionally for the new exports.
• docs/guide.html batch panel: documents the pattern with the real ar example and the routing/registry story; stale "graphqlBatchJobStore is planned" notes replaced.

Notes

• Branched off main, so no dependency on feat(batch): opt-in safety net for stranded pending rows #37 (safety net); the canonical store already exposes markStranded for when it lands.
• Consumer-side exemplar PR (monorepo service wiring) is opening separately against hopdrive/sdk monorepo-starter.

🤖 Generated with Claude Code