@venturekit/data 0.0.31 → 0.0.33

package/dist/query/secret.js

@@ -131,7 +131,7 @@ async function fetchAndApply(arn) {
                 `from Secrets Manager (secret: ${redactedArn}). If the Lambda runs in ` +
                 `a VPC, verify it has a route to Secrets Manager: a working NAT gateway/instance, ` +
                 `or a com.amazonaws.<region>.secretsmanager VPC interface endpoint. ` +
-                `Override the timeout via DB_SECRET_FETCH_TIMEOUT_MS.`);
+                `Override the timeout via DB_SECRET_FETCH_TIMEOUT_MS.`, { cause: err });
         }
         throw err;
     }

package/dist/query/secret.js.map

@@ -1 +1 @@
-{"version":3,"file":"secret.js","sourceRoot":"","sources":["../../src/query/secret.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"secret.js","sourceRoot":"","sources":["../../src/query/secret.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@venturekit/data",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "description": "Database and data layer for VentureKit",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "src/sql/*.sql"
   ],
   "repository": {
     "type": "git",
@@ -22,15 +23,34 @@
     "access": "public"
   },
   "license": "Apache-2.0",
+  "vk": {
+    "migrations": "src/sql"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./idempotency": {
+      "types": "./dist/idempotency/index.d.ts",
+      "import": "./dist/idempotency/index.js"
+    },
+    "./outbox": {
+      "types": "./dist/outbox/index.d.ts",
+      "import": "./dist/outbox/index.js"
+    },
+    "./jobs": {
+      "types": "./dist/jobs/index.d.ts",
+      "import": "./dist/jobs/index.js"
+    },
+    "./files": {
+      "types": "./dist/files/index.d.ts",
+      "import": "./dist/files/index.js"
     }
   },
   "dependencies": {
     "@aws-sdk/client-secrets-manager": "^3.1126.0",
-    "@venturekit/core": "0.0.31",
+    "@venturekit/core": "0.0.33",
     "pg": "^8.12.0"
   },
   "devDependencies": {

package/src/sql/0000_vk_data_foundation.sql

@@ -0,0 +1,305 @@
+-- @venturekit/data — multi-tenant Postgres foundation.
+--
+-- Functions created by this migration:
+--   vk_uuid_generate_v7()                      — time-ordered primary keys
+--   vk_tenant_scope()                          — every tenant this request may READ
+--   vk_acting_tenant()                         — the single tenant it may WRITE as
+--   vk_install_tenant_guards(schema, table, role)  — forced RLS + policy + grants
+--   vk_install_catalog_guards(schema, table, role) — read-only grants for shared catalogs
+--
+-- # Why this is the framework's job
+--
+-- `runWithTenantScope()` in this package publishes `app.tenant_id` and
+-- `app.tenant_ids` as Postgres GUCs. That is only half a tenancy feature: the
+-- GUCs do nothing until a policy reads them, and until now every consumer had
+-- to write that policy — and the `ENABLE`/`FORCE`/`GRANT` around it — by hand,
+-- once per table. A project with sixty tenant-scoped tables hand-writes ~300
+-- lines in which a single omission is invisible: the table still works, queries
+-- still return rows, and the only symptom is that one table has no isolation at
+-- all. Shipping the reader and the installer next to the writer of the GUCs
+-- makes that omission impossible to write by accident.
+--
+-- Row-level security is also the one guarantee that CANNOT move into
+-- application code: Postgres enforces it against the connection, which is
+-- exactly what makes it hold when a query forgets its WHERE clause.
+--
+-- # The role split RLS depends on
+--
+-- RLS is skipped for superusers, for roles with BYPASSRLS, and for a table's
+-- owner unless FORCE ROW LEVEL SECURITY is set. So:
+--
+--   * migrations run as the OWNER (they must create and alter tables);
+--   * the application connects as the tenant role — `DatabaseIntent.tenantRole`
+--     in `vk.config.ts` — which owns nothing and has neither attribute, and is
+--     granted only DML.
+--
+-- FORCE is set anyway, so even a mistaken connection as the owner is filtered.
+-- Local development against a superuser bypasses all of it, which is why
+-- isolation tests must connect as the tenant role explicitly or they pass while
+-- proving nothing.
+--
+-- Names are `vk_`-prefixed and unqualified, matching `vk_tenants` and
+-- `vk_notifications`: a package-owned object must not collide with a consumer's
+-- own, and creating a schema in someone else's database is not this package's
+-- call to make. A project that prefers its own namespace can wrap these —
+-- `CREATE OR REPLACE FUNCTION sys.tenant_scope() ... SELECT <schema>.vk_tenant_scope()`
+-- — which keeps one implementation while leaving existing call sites alone.
+--
+-- # Why the `0000_` filename prefix
+--
+-- The migration runner merges the project's own `.sql` files with every
+-- installed package's and applies them in ALPHABETIC order, which puts the
+-- conventional `vk_<pkg>_<NNN>_*` names *after* a project's `0xx_*` files. That
+-- is right for tables a project only reads, and wrong for these: a consumer's
+-- own migration calls `vk_install_tenant_guards(...)` as it creates each table,
+-- so the functions must already exist. Worse, a `LANGUAGE sql` wrapper around
+-- one of them is validated when it is CREATEd, so a project delegating to these
+-- would fail at migrate time rather than at call time.
+--
+-- So this file takes the same one-character departure, for the same reason, as
+-- `@venturekit-pro/tenancy`'s `0000_vk_tenancy_tenants.sql`: primordial-parent
+-- status. Sorting before `0000_vk_tenancy_*` is incidental - neither depends on
+-- the other.
+--
+-- # Effect on projects already in production
+--
+-- Additive, and safe to pick up late. The runner tracks applied files by name
+-- and applies any it has not seen, so an existing database simply gains these
+-- five functions on its next migrate; the `0000_` name does not imply
+-- re-running anything, and nothing here depends on schema that a later
+-- migration created. No existing file is touched, which is the thing that would
+-- break - `vk migrate` hashes every applied file and raises
+-- `MigrationHashMismatchError` if one changes. `pgcrypto` is already created by
+-- `@venturekit-pro/tenancy`.
+--
+-- Idempotent throughout (`CREATE OR REPLACE`, `IF NOT EXISTS`), so re-applying
+-- after a partial failure never breaks a deploy.
+
+-- ─── Extensions ─────────────────────────────────────────────────────────
+-- `pgcrypto` for gen_random_bytes, which the v7 generator below needs.
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- ─── Identifiers ────────────────────────────────────────────────────────
+
+/**
+ * Time-ordered uuid (RFC 9562 v7).
+ *
+ * v4 keys scatter inserts across the whole index, so a busy table's hot page
+ * set is the entire index rather than its right edge — measurable write
+ * amplification once a table is taking millions of rows a day. v7 puts a
+ * millisecond timestamp in the leading 48 bits, restoring insert locality while
+ * still not exposing a guessable sequence.
+ *
+ * `clock_timestamp()` rather than `now()`: `now()` is fixed for the whole
+ * transaction, so a bulk insert of 5 000 rows would emit 5 000 keys sharing one
+ * timestamp prefix and lose the ordering this exists to provide.
+ */
+CREATE OR REPLACE FUNCTION vk_uuid_generate_v7()
+RETURNS uuid
+LANGUAGE plpgsql
+VOLATILE
+PARALLEL SAFE
+AS $$
+DECLARE
+  ts_ms  bigint := (extract(epoch FROM clock_timestamp()) * 1000)::bigint;
+  raw    bytea;
+BEGIN
+  -- 48-bit big-endian millisecond timestamp, then 80 random bits.
+  raw := substring(int8send(ts_ms) FROM 3 FOR 6) || gen_random_bytes(10);
+  -- Version 7 in the high nibble of octet 6.
+  raw := set_byte(raw, 6, (get_byte(raw, 6) & 15) | 112);
+  -- RFC 4122 variant (10xx) in the high bits of octet 8.
+  raw := set_byte(raw, 8, (get_byte(raw, 8) & 63) | 128);
+  RETURN encode(raw, 'hex')::uuid;
+END;
+$$;
+
+COMMENT ON FUNCTION vk_uuid_generate_v7() IS
+  'Time-ordered uuid v7 (RFC 9562). Insert-local alternative to gen_random_uuid().';
+
+-- ─── Tenancy ────────────────────────────────────────────────────────────
+
+/**
+ * Every tenant the current request may READ, or NULL when un-scoped.
+ *
+ * Reads `app.tenant_ids`, published by this package's `runWithTenantScope()`.
+ * A parent tenant's request carries itself plus its descendants, so "a group
+ * owner sees their child tenants" is satisfied by this one policy instead of a
+ * branch in every query.
+ *
+ * NULL is the fail-closed sentinel: `x = ANY (NULL)` is NULL, so an un-scoped
+ * request sees nothing rather than everything. The `true` argument to
+ * `current_setting` makes an unset GUC return NULL instead of raising, which is
+ * what lets a migration or an admin connection run outside any request scope.
+ *
+ * STABLE, so the planner evaluates it once per statement rather than per row.
+ */
+CREATE OR REPLACE FUNCTION vk_tenant_scope()
+RETURNS uuid[]
+LANGUAGE sql
+STABLE
+PARALLEL SAFE
+AS $$
+  SELECT CASE
+           WHEN coalesce(current_setting('app.tenant_ids', true), '') = '' THEN NULL::uuid[]
+           ELSE string_to_array(current_setting('app.tenant_ids', true), ',')::uuid[]
+         END;
+$$;
+
+COMMENT ON FUNCTION vk_tenant_scope() IS
+  'Tenants readable by this request (app.tenant_ids). NULL = un-scoped = no rows.';
+
+/**
+ * The single tenant this request ACTS as — `app.tenant_id`, the acting tenant
+ * of the scope.
+ *
+ * Writes are checked against this, not against the whole scope: a parent-tenant
+ * administrator reading twelve child tenants should not be able to create a row
+ * in one of them by accident. Widening a write to another tenant has to be a
+ * deliberate re-scope, which is visible in the code that does it.
+ */
+CREATE OR REPLACE FUNCTION vk_acting_tenant()
+RETURNS uuid
+LANGUAGE sql
+STABLE
+PARALLEL SAFE
+AS $$
+  SELECT nullif(current_setting('app.tenant_id', true), '')::uuid;
+$$;
+
+COMMENT ON FUNCTION vk_acting_tenant() IS
+  'The tenant this request may WRITE as (app.tenant_id). NULL = un-scoped.';
+
+/**
+ * Attach the standard guards to a tenant-scoped table:
+ *
+ *   1. RLS, ENABLEd and FORCEd;
+ *   2. the isolation policy — read across the scope, write only as the acting
+ *      tenant;
+ *   3. DML grants for `p_role`.
+ *
+ * This is DDL run at migration time, not runtime behaviour: a macro that
+ * expands to the statements every tenant-scoped table needs.
+ *
+ * `p_role` is a parameter rather than a constant because the application role is
+ * the consumer's (`DatabaseIntent.tenantRole`), and a framework that hard-coded
+ * one would work for exactly one project. It is validated against `pg_roles`
+ * and interpolated with `%I`, so it cannot carry SQL.
+ *
+ * Idempotent, so re-running a migration during development is safe. The table
+ * must have a `tenant_id` column, asserted rather than assumed because a table
+ * that silently skipped its policy is exactly the failure this prevents.
+ */
+CREATE OR REPLACE FUNCTION vk_install_tenant_guards(
+  p_schema text,
+  p_table  text,
+  p_role   text
+)
+RETURNS void
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  qualified text := format('%I.%I', p_schema, p_table);
+  fn_schema text;
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = p_schema AND table_name = p_table AND column_name = 'tenant_id'
+  ) THEN
+    RAISE EXCEPTION 'vk_install_tenant_guards: %.% has no tenant_id column', p_schema, p_table;
+  END IF;
+
+  -- A missing role is a misconfiguration, not something to paper over: the
+  -- grant would fail anyway, and failing here names the cause.
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = p_role) THEN
+    RAISE EXCEPTION 'vk_install_tenant_guards: role % does not exist', p_role;
+  END IF;
+
+  /* The policy must name the scope functions SCHEMA-QUALIFIED.
+     A policy expression is re-resolved against the *querying* session's
+     `search_path`, not the one in effect when the policy was created. Left
+     bare, `vk_tenant_scope()` would fail — or, far worse, resolve to a
+     same-named function in a schema earlier on some connection's path, which
+     is a tenant-isolation bypass that no test connecting normally would see.
+     So resolve where this migration actually put them, once, here. */
+  SELECT n.nspname INTO fn_schema
+    FROM pg_proc p
+    JOIN pg_namespace n ON n.oid = p.pronamespace
+   WHERE p.proname = 'vk_tenant_scope'
+   LIMIT 1;
+
+  IF fn_schema IS NULL THEN
+    RAISE EXCEPTION 'vk_install_tenant_guards: vk_tenant_scope() not found — is @venturekit/data''s migration applied?';
+  END IF;
+
+  EXECUTE format('ALTER TABLE %s ENABLE ROW LEVEL SECURITY', qualified);
+  EXECUTE format('ALTER TABLE %s FORCE ROW LEVEL SECURITY', qualified);
+
+  EXECUTE format('DROP POLICY IF EXISTS tenant_isolation ON %s', qualified);
+  EXECUTE format(
+    'CREATE POLICY tenant_isolation ON %s
+       USING (tenant_id = ANY (%I.vk_tenant_scope()))
+       WITH CHECK (tenant_id = %I.vk_acting_tenant())',
+    qualified, fn_schema, fn_schema);
+
+  EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON %s TO %I', qualified, p_role);
+END;
+$$;
+
+COMMENT ON FUNCTION vk_install_tenant_guards(text, text, text) IS
+  'Attach forced RLS, the isolation policy and DML grants. Call once per tenant-scoped table.';
+
+/**
+ * Grants for a table that is deliberately NOT tenant-scoped — the shared
+ * catalogs every tenant reads and none may edit.
+ *
+ * Read-only to the application on purpose: these rows are curated centrally,
+ * and a tenant-facing service editing a shared catalog is how one tenant's
+ * data-entry mistake becomes everyone's.
+ */
+CREATE OR REPLACE FUNCTION vk_install_catalog_guards(
+  p_schema text,
+  p_table  text,
+  p_role   text
+)
+RETURNS void
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  qualified text := format('%I.%I', p_schema, p_table);
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = p_role) THEN
+    RAISE EXCEPTION 'vk_install_catalog_guards: role % does not exist', p_role;
+  END IF;
+
+  EXECUTE format('GRANT SELECT ON %s TO %I', qualified, p_role);
+END;
+$$;
+
+COMMENT ON FUNCTION vk_install_catalog_guards(text, text, text) IS
+  'Read-only grants for a shared, non-tenant-scoped catalog table.';
+
+-- ─── Auditing the result ────────────────────────────────────────────────
+--
+-- "Which tenant-scoped tables are missing RLS?" is a query, not a view, so it
+-- can live in the test that asserts it rather than in a schema object nobody
+-- reads:
+--
+--   SELECT c.relname
+--     FROM pg_class c
+--     JOIN pg_namespace n ON n.oid = c.relnamespace
+--    WHERE n.nspname = ANY ($1::text[])
+--      AND c.relkind = 'r'
+--      AND EXISTS (SELECT 1 FROM information_schema.columns
+--                   WHERE table_schema = n.nspname AND table_name = c.relname
+--                     AND column_name = 'tenant_id')
+--      AND NOT (c.relrowsecurity AND EXISTS (
+--                 SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid));
+--
+-- A table counts as protected when RLS is ENABLEd and at least one policy
+-- exists. FORCE is deliberately not required by that check: it applies the
+-- policy to the table owner too, and trusted processes that legitimately write
+-- across tenants (an event projector, an ingest listener, catalog seeds) run as
+-- the owner. What matters is that the tenant role — the only one serving user
+-- requests, and which owns nothing — is filtered. ENABLE plus a policy
+-- guarantees that.

package/src/sql/vk_data_001_idempotency.sql

@@ -0,0 +1,48 @@
+-- @venturekit/data — idempotency records.
+--
+-- Table created by this migration:
+--   vk_idempotency_record — stored responses for replayed unsafe requests
+--
+-- Backs `createPostgresIdempotencyStore()` (`src/idempotency/postgres.ts`),
+-- which plugs into `@venturekit/runtime`'s `idempotencyMiddleware`. That
+-- middleware has always taken a pluggable store and shipped two — in-memory
+-- (per-process, so wrong for Lambda) and DynamoDB — leaving a Postgres-only
+-- project to stand up a DynamoDB table for four columns.
+--
+-- Unlike `0000_vk_data_foundation.sql` this file keeps the
+-- conventional `vk_data_001_` name: nothing in a consumer's own migration
+-- references the table, so sorting after the project's `0xx_*` files is fine.
+--
+-- Additive for existing projects: one new table, no existing file edited, and
+-- nothing writes to it until a project wires the middleware.
+
+CREATE TABLE IF NOT EXISTS vk_idempotency_record (
+  -- The idempotency key, optionally namespaced by the store's `scope` as
+  -- `<scope>:<key>`. Scoping matters: the middleware's default extractor reads
+  -- a CLIENT-supplied header, so without it two callers sending the same key
+  -- collide and the second is served the first's cached response — across
+  -- tenants, a cross-tenant read. See the `scope` option.
+  key         text        PRIMARY KEY,
+  -- The serialized handler response, replayed verbatim on a duplicate.
+  -- Empty while status is 'pending'.
+  response    text        NOT NULL DEFAULT '',
+  -- 'pending' is written before the handler runs and is what makes a
+  -- concurrent duplicate detectable; 'completed' once the response is stored.
+  -- A CHECK rather than an enum: enums are a migration to extend, and these
+  -- two values are the middleware's whole vocabulary.
+  status      text        NOT NULL CHECK (status IN ('pending', 'completed')),
+  -- Absolute expiry. Reads filter on this, so an expired row is already
+  -- invisible whether or not anything has deleted it.
+  expires_at  timestamptz NOT NULL,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now()
+);
+
+-- Postgres has no TTL, so expired rows are deleted by
+-- `purgeExpiredIdempotencyRecords()` on a schedule. This index is what keeps
+-- that sweep from scanning the table.
+CREATE INDEX IF NOT EXISTS vk_idempotency_record_expires_at_idx
+  ON vk_idempotency_record (expires_at);
+
+COMMENT ON TABLE vk_idempotency_record IS
+  'Replay protection for unsafe requests. Backs @venturekit/data''s createPostgresIdempotencyStore().';

package/src/sql/vk_data_002_outbox.sql

@@ -0,0 +1,99 @@
+-- @venturekit/data — transactional outbox.
+--
+-- Table created by this migration:
+--   vk_outbox — domain events awaiting publication
+--
+-- Backs `createPostgresOutboxStore()` (`src/outbox/postgres.ts`), the storage
+-- half of `@venturekit/runtime/patterns`' outbox relay. `publishEvent()` puts an
+-- event on EventBridge now; this table is how an event becomes part of the
+-- transaction that caused it, so the two can never disagree about whether the
+-- state change happened.
+--
+-- Additive for existing projects: one new table, no existing file edited, and
+-- nothing writes to it until a project calls `appendToOutbox()`.
+
+CREATE TABLE IF NOT EXISTS vk_outbox (
+  -- Supplied by the writer, not defaulted, and expected to be a time-ordered
+  -- uuid v7 (`newEventId()` in the runtime, `vk_uuid_generate_v7()` in SQL).
+  -- This is the primary key of an append-only table AND every consumer's dedupe
+  -- key: a v4 scatters the index it is clustered on as the table grows, and an
+  -- append-only table only grows. No DEFAULT because an id the writer already
+  -- put on the wire must be the id stored here.
+  id              uuid        PRIMARY KEY,
+
+  -- The ordering key. A sequence, so ordering is assigned at insert by the
+  -- database rather than by a clock — two events a millisecond apart on
+  -- different connections still get a total order, which `occurred_at` cannot
+  -- promise. The relay sorts by this and the consumer keeps it as the source
+  -- version.
+  seq             bigserial   NOT NULL UNIQUE,
+
+  type            text        NOT NULL,
+
+  -- Ordering is guaranteed PER AGGREGATE, so these two columns are what the
+  -- relay's blocking is keyed on, not decoration.
+  aggregate_type  text        NOT NULL,
+  aggregate_id    text        NOT NULL,
+
+  -- NULL for platform-global facts that belong to no tenant.
+  tenant_id       uuid,
+
+  payload         jsonb       NOT NULL DEFAULT '{}'::jsonb,
+  -- Payload schema version. The envelope calls it `version`; the column is
+  -- `event_version` because `version` is a word Postgres tooling likes to use.
+  event_version   integer     NOT NULL DEFAULT 1,
+  -- When the business fact occurred, which is not when the row was inserted.
+  occurred_at     timestamptz NOT NULL DEFAULT now(),
+  -- `{ type: 'user' | 'system', id }`. jsonb rather than two columns so the
+  -- envelope round-trips without the adapter reassembling it.
+  actor           jsonb       NOT NULL,
+
+  correlation_id  text,
+  causation_id    text,
+
+  -- Publication state. NULL means pending; the relay sets it AFTER the bus has
+  -- accepted the event, never before — marking first turns a crash into an
+  -- event that no longer exists anywhere.
+  published_at    timestamptz,
+
+  -- Retry accounting. `attempts >= maxAttempts` is the quarantine, and the
+  -- relay's claim excludes both the quarantined row and anything queued behind
+  -- it for the same aggregate.
+  attempts        integer     NOT NULL DEFAULT 0,
+  last_error      text,
+  failed_at       timestamptz,
+
+  -- An operator deciding the event will never publish. Separate from `attempts`
+  -- on purpose: collapsing the two means raising the quarantine bound later
+  -- drags retired events back onto the bus. A discard also RELEASES the
+  -- successors held behind it, which is what makes quarantine a state an
+  -- aggregate can leave.
+  discarded_at    timestamptz,
+  discard_reason  text,
+
+  created_at      timestamptz NOT NULL DEFAULT now()
+);
+
+-- The relay's claim: pending, not discarded, not quarantined, oldest first.
+-- Partial, so it indexes only the rows that are actually claimable — which in a
+-- healthy system is a handful out of however many million have been published.
+CREATE INDEX IF NOT EXISTS vk_outbox_pending_seq_idx
+  ON vk_outbox (seq)
+  WHERE published_at IS NULL AND discarded_at IS NULL;
+
+-- The `blocked` CTE in `claim()`: which aggregates have an abandoned event.
+CREATE INDEX IF NOT EXISTS vk_outbox_blocked_idx
+  ON vk_outbox (aggregate_type, aggregate_id)
+  WHERE published_at IS NULL AND discarded_at IS NULL;
+
+-- "What is stuck, and why" — the operator's query, and the one a dashboard runs.
+CREATE INDEX IF NOT EXISTS vk_outbox_quarantined_idx
+  ON vk_outbox (failed_at DESC)
+  WHERE published_at IS NULL AND discarded_at IS NULL AND attempts > 0;
+
+COMMENT ON TABLE vk_outbox IS
+  'Transactional outbox. Events are appended in the caller''s transaction and relayed by @venturekit/runtime''s relayOnce().';
+COMMENT ON COLUMN vk_outbox.seq IS
+  'Ordering key assigned at insert. The relay guarantees per-aggregate order by this, and never publishes an event while an earlier one for the same aggregate is unpublished.';
+COMMENT ON COLUMN vk_outbox.discarded_at IS
+  'Operator retired this event. Leaves attempts untouched and releases successors of the same aggregate.';

package/src/sql/vk_data_003_jobs.sql

@@ -0,0 +1,114 @@
+-- @venturekit/data — durable background jobs.
+--
+-- Table created by this migration:
+--   vk_job — queued work, in Postgres rather than SQS
+--
+-- Backs `@venturekit/data/jobs`.
+--
+-- # Why this exists next to the SQS `queues` intent rather than instead of it
+--
+-- SQS is the right tool for fire-and-forget fan-out and it stays the default.
+-- What it cannot do is answer a question about work in flight. "Which imports
+-- are still geocoding for this tenant" is a screen in the product, and a queue
+-- has no query surface: messages are invisible until received, and received
+-- messages are invisible to everyone else. Rebuilding that visibility on top of
+-- SQS means a second table tracking what you put in the queue — at which point
+-- the queue is the redundant half, because the table can be claimed from
+-- directly.
+--
+-- So: reach for `queues` when the work is opaque and throughput matters, and for
+-- this when the work is a thing the product talks about — an import, a export, a
+-- recompute someone is waiting on.
+--
+-- Claiming uses FOR UPDATE SKIP LOCKED, which lets several workers share the
+-- table without a lock convoy: each transaction takes rows nobody else holds and
+-- skips the rest rather than queueing behind them.
+--
+-- Additive for existing projects: one new table, no existing file edited, and
+-- nothing writes to it until a project calls `enqueueJob()`.
+
+CREATE TABLE IF NOT EXISTS vk_job (
+  id            uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  -- NULL for platform-wide work (partition maintenance, a global recompute).
+  -- Deliberately no foreign key: the table a tenant lives in is the consumer's
+  -- (`vk_tenants` only exists if @venturekit-pro/tenancy is installed), and a
+  -- framework-owned FK into an optional package's table would make this
+  -- migration fail for everyone who does not use it.
+  tenant_id     uuid,
+
+  -- Dispatch key. `runJobsOnce()` maps this to a handler, so it is the contract
+  -- between whoever enqueues and whoever runs.
+  kind          text        NOT NULL,
+  payload       jsonb       NOT NULL DEFAULT '{}'::jsonb,
+
+  -- text + CHECK rather than an enum: an enum is a new type in the consumer's
+  -- schema and a migration to extend, and this vocabulary is closed anyway.
+  status        text        NOT NULL DEFAULT 'queued'
+                            CHECK (status IN ('queued', 'running', 'succeeded', 'failed', 'cancelled')),
+
+  -- Scheduling and retry are the SAME mechanism: a failed job is re-queued with
+  -- a later `run_after`, and a job scheduled for tomorrow is just one with a
+  -- distant `run_after`. One column, so there is no way for the two to disagree.
+  run_after     timestamptz NOT NULL DEFAULT now(),
+
+  attempts      integer     NOT NULL DEFAULT 0,
+  max_attempts  integer     NOT NULL DEFAULT 5,
+
+  -- Held while a worker owns the row. A worker that crashes leaves these set
+  -- and the row in 'running' forever, which is what `reclaimStuckJobs()` looks
+  -- for: 'running' plus an old `locked_at` is indistinguishable from a dead
+  -- worker, and treating it as one is the only way the work resumes.
+  locked_at     timestamptz,
+  locked_by     text,
+
+  last_error    text,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  finished_at   timestamptz,
+
+  CONSTRAINT vk_job_attempts_within_max CHECK (attempts <= max_attempts),
+  -- At least one, because the claim increments `attempts` before the handler
+  -- runs: with a bound of zero the first claim would violate the check above
+  -- and the job could never be taken at all.
+  CONSTRAINT vk_job_max_attempts_positive CHECK (max_attempts >= 1)
+);
+
+-- The claim: due, runnable, oldest first. Partial, so it indexes only the rows
+-- a worker can take rather than every job ever run.
+CREATE INDEX IF NOT EXISTS vk_job_runnable_idx
+  ON vk_job (run_after)
+  WHERE status = 'queued';
+
+-- The product's per-tenant job list — the query this table exists to make
+-- possible.
+CREATE INDEX IF NOT EXISTS vk_job_tenant_status_idx
+  ON vk_job (tenant_id, status, created_at DESC);
+
+-- Finding work abandoned by a dead worker.
+CREATE INDEX IF NOT EXISTS vk_job_stuck_idx
+  ON vk_job (locked_at)
+  WHERE status = 'running';
+
+-- # On row-level security
+--
+-- `vk_install_tenant_guards()` is deliberately NOT applied here, for two
+-- reasons that are both about the worker rather than the reader:
+--
+--   1. `tenant_id` is nullable, and RLS would make platform-wide rows invisible
+--      to the very process that has to run them;
+--   2. a worker runs outside any request, so there is no acting tenant to scope
+--      to — it processes every tenant's work by design.
+--
+-- Reads that serve a REQUEST must therefore carry the scope themselves, which
+-- `listJobs()` does (`tenant_id = ANY (vk_tenant_scope())` when a scope is
+-- engaged). That is the same predicate the policy would have applied, so a
+-- caller who goes through the helper cannot see another tenant's work; a caller
+-- who writes their own SQL against this table is responsible for the clause.
+
+COMMENT ON TABLE vk_job IS
+  'Durable background work, claimable with FOR UPDATE SKIP LOCKED. In Postgres so that work in flight is queryable; see @venturekit/data/jobs.';
+COMMENT ON COLUMN vk_job.run_after IS
+  'Earliest time this job may run. Retry backoff and future scheduling are the same mechanism.';
+COMMENT ON COLUMN vk_job.locked_at IS
+  'Set while a worker holds the row. Old + status running = a dead worker; reclaimStuckJobs() re-queues it.';