@stackbone/cli 0.6.1 → 0.6.3

package/migrations/0090_trigger_subscriptions_sample_event.sql

@@ -0,0 +1,14 @@
+-- 0090_trigger_subscriptions_sample_event.sql — the first real event a link received (PLA-1900)
+-- A trigger's declared `sampleData` is the only thing the mapper can derive event fields
+-- from when the trigger publishes no `outputSchema`, and 49 Activepieces polling triggers
+-- declare it as `{}` (Gmail's `gmail_new_email_received` among them). Their links offered
+-- no field to wire. The link now keeps the first real event it delivers, and the mapper
+-- reads that instead.
+--
+-- Written by the intake tick, never by an operator, and only while it is still NULL: the
+-- first event wins and a later one never replaces it. The tick bounds it before writing
+-- (long strings and arrays clipped), because `list()` returns this column for every link.
+-- Nullable: NULL is "no sample yet", which every link that existed before this reads as.
+
+ALTER TABLE stackbone_platform.trigger_subscriptions
+ADD COLUMN IF NOT EXISTS sample_event jsonb;

package/migrations/0091_echo_guard_checks.sql

@@ -0,0 +1,32 @@
+-- 0091_echo_guard_checks.sql — the runs that asked the self-write guard (PLA-1580)
+-- A workflow that answers a connector trigger and writes back through the same
+-- connection raises the event that trigger reads, so it starts itself again.
+-- `isOwnEcho` stops that, and until now nothing recorded that a run called it:
+-- the guard is a read, and it left no trace. The box now writes one row here per
+-- run and connector the first time a run asks, whatever the guard answers, so the
+-- link-level warning can leave a guarded run out.
+--
+-- One row per (run, connector), never one per call: the warning asks "did this run
+-- guard this connector", and a run that asks a hundred times is the same answer.
+-- The connector is compared exactly, like every connector id: a guard on `slack`
+-- does not cover `linear`.
+--
+-- ON DELETE CASCADE from the run, the same as `run_steps`: a marker means nothing
+-- once the run it describes is gone.
+CREATE TABLE IF NOT EXISTS stackbone_platform.echo_guard_checks (
+    run_id      uuid        NOT NULL
+                            REFERENCES stackbone_platform.runs(id) ON DELETE CASCADE,
+    connector   text        NOT NULL,
+    created_at  timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (run_id, connector)
+);
+
+-- The warning reads the runs ONE link started or resumed inside a short window,
+-- once per link on every `GET /api/trigger-subscriptions`. 0075 left `trigger_ref`
+-- unindexed because nothing filtered on it; this is that reader. On `started_at`
+-- rather than `created_at` because a resume re-arms the row and moves `started_at`
+-- to the resume, so a run that woke up and wrote is read by when it woke. Partial,
+-- so only `event` runs (the only ones that carry a ref) pay for it on write.
+CREATE INDEX IF NOT EXISTS runs_trigger_ref_started_at_idx
+    ON stackbone_platform.runs (trigger_ref, started_at DESC)
+    WHERE trigger_ref IS NOT NULL;

package/migrations/0092_trigger_subscriptions_outlook_new_email.sql

@@ -0,0 +1,522 @@
+-- 0092_trigger_subscriptions_outlook_new_email.sql — the `outlook-app-only` links
+-- move to the `microsoft-outlook` piece's `newEmail` (PLA-1932).
+--
+-- Both Outlook built-ins left the catalog: the one `microsoft-outlook` piece takes
+-- either grant (PLA-1838) and its `newEmail` replaces their `message-received`.
+-- Same folder (the Inbox), same `receivedDateTime gt` filter, every sender. What
+-- differs is the event and where the mailbox lives, so each link is rewritten in
+-- place, on the box that holds it, when that box boots: a box on a laptop is
+-- converted by starting it, with nothing to run by hand.
+--
+-- Per link, `connector = 'outlook-app-only' AND trigger_id = 'message-received'`,
+-- matched exactly (never `LIKE`: `outlook-app-only-2`, `outlook-catalog` and the
+-- delegated `outlook` are other rows):
+--
+--   * the cursor. The built-in kept the ISO stamp of the newest mail it read; the
+--     piece's TIMEBASED poll reads `{ "lastPoll": <epoch ms> }` and throws on
+--     anything else, and filters `receivedDateTime gt` that instant, so the link
+--     resumes where it stopped. Only a stamp with an explicit offset is read: one
+--     without would be read in the session's time zone, and a guess is worse than
+--     a link that refuses to poll. Anything else stays as it was (and is reported
+--     below) rather than becoming epoch 0, which would replay the Inbox. A NULL
+--     cursor stays NULL: arming the link runs the piece's own `onEnable`.
+--   * the mapping. The built-in's event was its own flat map of Graph's message;
+--     the piece's is the message as Graph answers it. A field the mapping reads
+--     OFF THE EVENT is renamed: `messageId` to `id`, `snippet` to `bodyPreview`,
+--     `date` to `receivedDateTime`, and `mailbox`, which the link stamped on, to
+--     the mailbox itself as a string. Strings, later steps of a path, variables
+--     and functions are never touched. The rewrite reads the JSONata token by
+--     token; where it cannot be sure what a name reads (a predicate, a lambda,
+--     the context `$` read whole or by name, an operator it does not model) it
+--     leaves the mapping exactly as it was and reports it. That mapping fails at
+--     the next event, where the operator sees it; a mangled one would keep
+--     running with wrong data. A link with no mapping handed the workflow the
+--     event itself, so it is given one that spells that event out.
+--   * the mailbox goes from the link (`scope` `user-id`) to the connection, where
+--     the piece reads it. The connector row is converted beside this, by the box
+--     (`connect-tables.ts`) and by db-core 0038, before this runs.
+--   * what described the old event goes: `mapping_graph` when the mapping
+--     changed (it would compile back to the old names), and `sample_event`.
+--   * `poll_revision` moves, so a poll result read before this is not saved.
+--
+-- The delivery journal needs nothing: both triggers key a delivery on Graph's
+-- message id, so mail delivered before the move is not delivered again.
+
+CREATE FUNCTION stackbone_platform.pla1932_last_poll(stored jsonb) RETURNS jsonb
+LANGUAGE plpgsql AS $fn$
+DECLARE
+  stamp text;
+  instant timestamptz;
+BEGIN
+  IF stored IS NULL OR jsonb_typeof(stored) <> 'string' THEN
+    RETURN NULL;
+  END IF;
+  stamp := stored #>> '{}';
+  IF stamp !~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$' THEN
+    RETURN NULL;
+  END IF;
+  BEGIN
+    instant := stamp::timestamptz;
+  EXCEPTION WHEN others THEN
+    RETURN NULL;
+  END;
+  RETURN jsonb_build_object('lastPoll', floor(extract(epoch FROM instant) * 1000)::bigint);
+END;
+$fn$;
+
+-- The JSONata over `message-received`'s event, rewritten over `newEmail`'s, or
+-- NULL when it cannot be done with certainty. `context_is_event` tracks whether a
+-- bare name at this point reads the event: true at the top, in a call's arguments,
+-- in a group, an array or an object; false inside a predicate, a lambda body, a
+-- block or object applied to a path, and a sort.
+CREATE FUNCTION stackbone_platform.pla1932_new_email_jsonata(expr text, mailbox text)
+RETURNS text
+LANGUAGE plpgsql AS $fn$
+DECLARE
+  -- Anything that ends a name: JSONata's operators, quotes and whitespace.
+  ends_name constant text := '[][{}().,;:?+*/%|=<>^&!~@#"''`$[:space:]-]';
+  n int := length(expr);
+  i int := 1;
+  j int;
+  c text;
+  nx text;
+  out text := '';
+  tok text;
+  word text;
+  quoted boolean;
+  is_field boolean;
+  -- The open brackets, innermost last, and what each one means.
+  opener text[] := '{}';
+  reads_event boolean[] := '{}';
+  is_object boolean[] := '{}';
+  reading_key boolean[] := '{}';
+  questions int[] := '{}';
+  is_params boolean[] := '{}';
+  depth int := 0;
+  top_questions int := 0;
+  context_is_event boolean := true;
+  closed_params boolean;
+  -- What came before: start, value, var, ctx (a bare `$`/`$$`), dot, op, open,
+  -- comma, colon, fn (`function`), params (a lambda's closed parameter list).
+  prev text := 'start';
+  before_dot text := 'other';
+BEGIN
+  IF expr IS NULL THEN
+    RETURN NULL;
+  END IF;
+  WHILE i <= n LOOP
+    c := substr(expr, i, 1);
+    nx := substr(expr, i + 1, 1);
+
+    IF c ~ '[[:space:]]' THEN
+      out := out || c;
+      i := i + 1;
+      CONTINUE;
+    END IF;
+
+    IF c = '/' AND nx = '*' THEN
+      j := strpos(substr(expr, i + 2), '*/');
+      IF j = 0 THEN
+        RETURN NULL;
+      END IF;
+      out := out || substr(expr, i, j + 3);
+      i := i + j + 3;
+      CONTINUE;
+    END IF;
+
+    -- The context itself is understood only as `$.<field>`.
+    IF prev = 'ctx' AND c <> '.' THEN
+      RETURN NULL;
+    END IF;
+
+    IF c = '"' OR c = '''' THEN
+      j := i + 1;
+      LOOP
+        IF j > n THEN
+          RETURN NULL;
+        END IF;
+        IF substr(expr, j, 1) = '\' THEN
+          j := j + 2;
+          CONTINUE;
+        END IF;
+        EXIT WHEN substr(expr, j, 1) = c;
+        j := j + 1;
+      END LOOP;
+      out := out || substr(expr, i, j - i + 1);
+      i := j + 1;
+      prev := 'value';
+      CONTINUE;
+    END IF;
+
+    -- A regex literal stands where an operand does; elsewhere `/` divides.
+    IF c = '/' AND prev NOT IN ('value', 'var') THEN
+      j := i + 1;
+      LOOP
+        IF j > n THEN
+          RETURN NULL;
+        END IF;
+        IF substr(expr, j, 1) = '\' THEN
+          j := j + 2;
+          CONTINUE;
+        END IF;
+        EXIT WHEN substr(expr, j, 1) = '/';
+        j := j + 1;
+      END LOOP;
+      j := j + 1;
+      WHILE j <= n AND substr(expr, j, 1) ~ '[a-z]' LOOP
+        j := j + 1;
+      END LOOP;
+      out := out || substr(expr, i, j - i);
+      i := j;
+      prev := 'value';
+      CONTINUE;
+    END IF;
+
+    IF c = '$' THEN
+      j := i + 1;
+      IF nx = '$' THEN
+        j := j + 1;
+      ELSE
+        WHILE j <= n AND substr(expr, j, 1) !~ ends_name LOOP
+          j := j + 1;
+        END LOOP;
+      END IF;
+      tok := substr(expr, i, j - i);
+      out := out || tok;
+      i := j;
+      prev := CASE WHEN tok IN ('$', '$$') AND context_is_event THEN 'ctx' ELSE 'var' END;
+      CONTINUE;
+    END IF;
+
+    IF c ~ '[0-9]' THEN
+      j := i;
+      WHILE j <= n AND substr(expr, j, 1) ~ '[0-9]' LOOP
+        j := j + 1;
+      END LOOP;
+      IF substr(expr, j, 1) = '.' AND substr(expr, j + 1, 1) ~ '[0-9]' THEN
+        j := j + 1;
+        WHILE j <= n AND substr(expr, j, 1) ~ '[0-9]' LOOP
+          j := j + 1;
+        END LOOP;
+      END IF;
+      IF substr(expr, j, 2) ~ '^[eE][0-9]' OR substr(expr, j, 3) ~ '^[eE][+-][0-9]' THEN
+        j := j + 2;
+        WHILE j <= n AND substr(expr, j, 1) ~ '[0-9]' LOOP
+          j := j + 1;
+        END LOOP;
+      END IF;
+      out := out || substr(expr, i, j - i);
+      i := j;
+      prev := 'value';
+      CONTINUE;
+    END IF;
+
+    IF c = '`' OR c !~ ends_name THEN
+      IF c = '`' THEN
+        j := strpos(substr(expr, i + 1), '`');
+        IF j = 0 THEN
+          RETURN NULL;
+        END IF;
+        word := substr(expr, i + 1, j - 1);
+        tok := substr(expr, i, j + 1);
+        quoted := true;
+        i := i + j + 1;
+      ELSE
+        j := i;
+        WHILE j <= n AND substr(expr, j, 1) !~ ends_name LOOP
+          j := j + 1;
+        END LOOP;
+        word := substr(expr, i, j - i);
+        tok := word;
+        quoted := false;
+        i := j;
+      END IF;
+
+      IF NOT quoted AND word IN ('and', 'or', 'in') THEN
+        out := out || tok;
+        prev := 'op';
+        CONTINUE;
+      END IF;
+      IF NOT quoted AND word IN ('true', 'false', 'null') THEN
+        out := out || tok;
+        prev := 'value';
+        CONTINUE;
+      END IF;
+      IF NOT quoted AND word IN ('function', 'λ') THEN
+        out := out || tok;
+        prev := 'fn';
+        CONTINUE;
+      END IF;
+
+      is_field := word IN ('messageId', 'snippet', 'date', 'mailbox');
+      IF prev = 'dot' THEN
+        -- A later step of a path: another object's field, unless the step before
+        -- it is the context or a variable, whose value is unknown here.
+        IF is_field AND before_dot IN ('ctx', 'var') THEN
+          RETURN NULL;
+        END IF;
+        out := out || tok;
+        prev := 'value';
+        CONTINUE;
+      END IF;
+
+      IF NOT is_field THEN
+        out := out || tok;
+      ELSIF NOT context_is_event THEN
+        RETURN NULL;
+      ELSIF depth > 0 AND is_object[depth] AND reading_key[depth] THEN
+        -- An unquoted key is an expression: renaming it would rename the key.
+        RETURN NULL;
+      ELSIF word = 'mailbox' THEN
+        IF mailbox IS NULL THEN
+          RETURN NULL;
+        END IF;
+        -- The mailbox becomes a string, which has no field, no index and no call.
+        j := i;
+        WHILE j <= n AND substr(expr, j, 1) ~ '[[:space:]]' LOOP
+          j := j + 1;
+        END LOOP;
+        IF substr(expr, j, 1) IN ('.', '[', '(', '{', '/', '`') THEN
+          RETURN NULL;
+        END IF;
+        out := out || to_json(mailbox)::text;
+      ELSE
+        tok := CASE word
+          WHEN 'messageId' THEN 'id'
+          WHEN 'snippet' THEN 'bodyPreview'
+          ELSE 'receivedDateTime'
+        END;
+        out := out || CASE WHEN quoted THEN '`' || tok || '`' ELSE tok END;
+      END IF;
+      prev := 'value';
+      CONTINUE;
+    END IF;
+
+    IF c = '.' THEN
+      IF nx = '.' THEN
+        out := out || '..';
+        i := i + 2;
+        prev := 'op';
+        CONTINUE;
+      END IF;
+      before_dot := CASE WHEN prev IN ('ctx', 'var') THEN prev ELSE 'other' END;
+      out := out || c;
+      i := i + 1;
+      prev := 'dot';
+      CONTINUE;
+    END IF;
+
+    IF c IN ('(', '[', '{') OR (c = '^' AND nx = '(') THEN
+      depth := depth + 1;
+      opener[depth] := CASE WHEN c = '^' THEN '(' ELSE c END;
+      is_object[depth] := false;
+      reading_key[depth] := false;
+      questions[depth] := 0;
+      is_params[depth] := false;
+      IF c = '^' THEN
+        -- A sort's terms read each item.
+        reads_event[depth] := false;
+        out := out || '^(';
+        i := i + 2;
+      ELSE
+        IF c = '(' THEN
+          is_params[depth] := prev = 'fn';
+          -- A call's arguments and a group read the same context; a lambda's
+          -- parameters and a block applied to a path do not.
+          reads_event[depth] := context_is_event AND prev NOT IN ('fn', 'dot');
+        ELSIF c = '[' THEN
+          -- After a value it filters that value; at an operand it builds an array.
+          reads_event[depth] := context_is_event AND prev NOT IN ('value', 'var', 'dot');
+        ELSE
+          is_object[depth] := prev <> 'params';
+          reading_key[depth] := prev <> 'params';
+          -- An object built at an operand reads the context; after a path it
+          -- groups that path's items, and after a lambda's parameters it is the
+          -- lambda's body.
+          reads_event[depth] := context_is_event AND prev NOT IN ('value', 'var', 'dot', 'params');
+        END IF;
+        out := out || c;
+        i := i + 1;
+      END IF;
+      context_is_event := reads_event[depth];
+      prev := 'open';
+      CONTINUE;
+    END IF;
+
+    IF c IN (')', ']', '}') THEN
+      IF depth = 0 OR opener[depth] <> (CASE c WHEN ')' THEN '(' WHEN ']' THEN '[' ELSE '{' END) THEN
+        RETURN NULL;
+      END IF;
+      closed_params := is_params[depth];
+      depth := depth - 1;
+      context_is_event := CASE WHEN depth = 0 THEN true ELSE reads_event[depth] END;
+      out := out || c;
+      i := i + 1;
+      prev := CASE WHEN closed_params THEN 'params' ELSE 'value' END;
+      CONTINUE;
+    END IF;
+
+    IF c = ',' THEN
+      IF depth > 0 AND is_object[depth] THEN
+        reading_key[depth] := true;
+        questions[depth] := 0;
+      END IF;
+      out := out || c;
+      i := i + 1;
+      prev := 'comma';
+      CONTINUE;
+    END IF;
+
+    IF c = ':' THEN
+      IF nx = '=' THEN
+        out := out || ':=';
+        i := i + 2;
+        prev := 'op';
+        CONTINUE;
+      END IF;
+      IF depth > 0 AND questions[depth] > 0 THEN
+        questions[depth] := questions[depth] - 1;
+        prev := 'op';
+      ELSIF depth = 0 AND top_questions > 0 THEN
+        top_questions := top_questions - 1;
+        prev := 'op';
+      ELSIF depth > 0 AND is_object[depth] AND reading_key[depth] THEN
+        reading_key[depth] := false;
+        prev := 'colon';
+      ELSE
+        RETURN NULL;
+      END IF;
+      out := out || c;
+      i := i + 1;
+      CONTINUE;
+    END IF;
+
+    IF c = '?' THEN
+      IF nx IN (':', '?') THEN
+        out := out || c || nx;
+        i := i + 2;
+      ELSE
+        IF depth > 0 THEN
+          questions[depth] := questions[depth] + 1;
+        ELSE
+          top_questions := top_questions + 1;
+        END IF;
+        out := out || c;
+        i := i + 1;
+      END IF;
+      prev := 'op';
+      CONTINUE;
+    END IF;
+
+    IF c = '*' THEN
+      IF nx = '*' THEN
+        RETURN NULL;
+      END IF;
+      IF prev IN ('value', 'var') THEN
+        prev := 'op';
+      ELSIF prev = 'dot' OR NOT context_is_event THEN
+        prev := 'value';
+      ELSE
+        -- Every field of the event at once.
+        RETURN NULL;
+      END IF;
+      out := out || c;
+      i := i + 1;
+      CONTINUE;
+    END IF;
+
+    IF (c = '~' AND nx = '>') OR (c = '!' AND nx = '=') OR (c IN ('<', '>') AND nx = '=') THEN
+      out := out || c || nx;
+      i := i + 2;
+      prev := 'op';
+      CONTINUE;
+    END IF;
+
+    IF c IN (';', '=', '<', '>', '+', '-', '&', '/') THEN
+      out := out || c;
+      i := i + 1;
+      prev := 'op';
+      CONTINUE;
+    END IF;
+
+    -- `|` (transform), `@` and `#` (bindings), `%` (parent or modulo), a lone `~`,
+    -- `!` or `^`, and anything else: not modelled.
+    RETURN NULL;
+  END LOOP;
+
+  IF depth <> 0 OR prev = 'ctx' THEN
+    RETURN NULL;
+  END IF;
+  RETURN out;
+END;
+$fn$;
+
+DO $$
+DECLARE
+  link record;
+  v_mailbox text;
+  v_cursor jsonb;
+  v_mapping text;
+  v_correlation text;
+BEGIN
+  FOR link IN
+    SELECT id, scope, poll_cursor, mapping, correlation_key
+      FROM stackbone_platform.trigger_subscriptions
+     WHERE connector = 'outlook-app-only'
+       AND trigger_id = 'message-received'
+     ORDER BY created_at, id
+       FOR UPDATE
+  LOOP
+    v_mailbox := nullif(btrim(link.scope ->> 'user-id'), '');
+
+    v_cursor := link.poll_cursor;
+    IF link.poll_cursor IS NOT NULL THEN
+      v_cursor := stackbone_platform.pla1932_last_poll(link.poll_cursor);
+      IF v_cursor IS NULL THEN
+        v_cursor := link.poll_cursor;
+        RAISE WARNING 'PLA-1932: trigger link % keeps its cursor %: it is no timestamp newEmail can resume from. Arm the link again, starting from now.',
+          link.id, link.poll_cursor;
+      END IF;
+    END IF;
+
+    IF link.mapping IS NULL THEN
+      v_mapping := '{ "messageId": id, "conversationId": conversationId, "from": from, "subject": subject, "snippet": bodyPreview, "date": receivedDateTime, "isRead": isRead'
+        || CASE WHEN v_mailbox IS NULL THEN '' ELSE ', "mailbox": ' || to_json(v_mailbox)::text END
+        || ' }';
+    ELSE
+      v_mapping := stackbone_platform.pla1932_new_email_jsonata(link.mapping, v_mailbox);
+      IF v_mapping IS NULL THEN
+        v_mapping := link.mapping;
+        RAISE WARNING 'PLA-1932: trigger link % keeps its mapping as it was: rewrite it over the newEmail event (id, bodyPreview, receivedDateTime, and the mailbox as a string).',
+          link.id;
+      END IF;
+    END IF;
+
+    v_correlation := link.correlation_key;
+    IF link.correlation_key IS NOT NULL THEN
+      v_correlation := coalesce(
+        stackbone_platform.pla1932_new_email_jsonata(link.correlation_key, v_mailbox),
+        link.correlation_key
+      );
+    END IF;
+
+    UPDATE stackbone_platform.trigger_subscriptions
+       SET connector = 'microsoft-outlook',
+           trigger_id = 'newEmail',
+           poll_cursor = v_cursor,
+           mapping = v_mapping,
+           mapping_graph = CASE
+             WHEN v_mapping IS DISTINCT FROM link.mapping THEN NULL
+             ELSE mapping_graph
+           END,
+           correlation_key = v_correlation,
+           scope = NULL,
+           sample_event = NULL,
+           poll_revision = poll_revision + 1,
+           updated_at = now()
+     WHERE id = link.id;
+  END LOOP;
+END $$;
+
+DROP FUNCTION stackbone_platform.pla1932_last_poll(jsonb);
+DROP FUNCTION stackbone_platform.pla1932_new_email_jsonata(text, text);

package/migrations/0093_trigger_subscriptions_webhook_token.sql

@@ -0,0 +1,13 @@
+-- 0093_trigger_subscriptions_webhook_token.sql — a webhook link's ingress token (PLA-1856)
+-- A piece's WEBHOOK trigger is delivered by the provider POSTing to the box at
+-- `/api/hooks/<link id>/<token>`. The route is public, so the token is the credential:
+-- 128 random bits, minted when the link arms, cleared when it disarms and minted
+-- again on the next arm, so a URL the provider held before stops answering.
+--
+-- Plaintext, compared in constant time: `onDisable` is handed the same URL `onEnable`
+-- registered, which a digest could not rebuild. Never returned by a list or a read.
+-- Nullable: NULL is "no ingress", which every polling link and every link that is off
+-- reads as.
+
+ALTER TABLE stackbone_platform.trigger_subscriptions
+ADD COLUMN IF NOT EXISTS webhook_token text;

package/migrations/0094_rag_document_versions.sql

@@ -0,0 +1,61 @@
+-- 0094_rag_document_versions.sql — RAG document versions (STA3-8)
+-- Every version of a document is its own row, with its own `source` (its storage
+-- key) and its own chunks, so rollback flips a flag and re-embeds nothing. The
+-- versions of one document share a `document_key`; the agent reads only the
+-- `is_active` one.
+--
+-- A document that existed before this is its own version 1, published, keyed by
+-- its `source`.
+
+ALTER TABLE stackbone_platform.rag_documents
+ADD COLUMN IF NOT EXISTS document_key text,
+ADD COLUMN IF NOT EXISTS version integer NOT NULL DEFAULT 1,
+ADD COLUMN IF NOT EXISTS is_active boolean NOT NULL DEFAULT true;
+
+-- Two overlapping ingests of one source could leave two rows before PLA-2327's
+-- lock. The newest keeps the source as its key; the older ones become documents
+-- of their own, still published, so nothing the agent reads changes and the
+-- unique index below can build. Deleting them would lose data.
+UPDATE stackbone_platform.rag_documents d
+SET document_key = CASE WHEN ranked.rn = 1 THEN d.source ELSE d.source || '#' || d.id END
+FROM (
+  SELECT id, row_number() OVER (
+    PARTITION BY collection_id, source ORDER BY created_at DESC, id DESC
+  ) AS rn
+  FROM stackbone_platform.rag_documents
+  WHERE document_key IS NULL
+) ranked
+WHERE d.id = ranked.id;
+
+-- Postgres cannot default one column to another. A workspace on an SDK older
+-- than this migration inserts without the key, so the trigger fills it in
+-- instead of failing every ingest on NOT NULL.
+CREATE OR REPLACE FUNCTION stackbone_platform.rag_documents_default_key()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  NEW.document_key := COALESCE(NEW.document_key, NEW.source);
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS rag_documents_default_key ON stackbone_platform.rag_documents;
+CREATE TRIGGER rag_documents_default_key
+BEFORE INSERT ON stackbone_platform.rag_documents
+FOR EACH ROW EXECUTE FUNCTION stackbone_platform.rag_documents_default_key();
+
+ALTER TABLE stackbone_platform.rag_documents
+ALTER COLUMN document_key SET NOT NULL;
+
+-- At most one published version per document. Non-deferrable, so publishing is
+-- two statements (unpublish the siblings, then publish the target): one swapping
+-- UPDATE can reach the target before the sibling and fail on the check.
+CREATE UNIQUE INDEX IF NOT EXISTS rag_documents_active_key_uq
+ON stackbone_platform.rag_documents (collection_id, document_key)
+WHERE is_active;
+
+-- Covers unpublished versions too: a writer that misses the key lock and hands
+-- out a version number twice fails here instead of leaving two v2s behind.
+CREATE UNIQUE INDEX IF NOT EXISTS rag_documents_key_version_uq
+ON stackbone_platform.rag_documents (collection_id, document_key, version);

package/migrations/0095_rag_document_version_counters.sql

@@ -0,0 +1,22 @@
+-- 0095_rag_document_version_counters.sql — a version number is never reused (STA3-8 D11)
+-- The last version number each document handed out. Numbering from the rows
+-- left (`max(version) + 1`) gave a deleted draft's number to the next upload,
+-- and the activity log then showed "deleted v3" next to a live, different v3.
+-- A new version takes this counter or the rows' highest version, whichever is
+-- greater, plus one, under the document's key lock. Deleting the whole document
+-- drops its row; deleting one version leaves it alone.
+
+CREATE TABLE IF NOT EXISTS stackbone_platform.rag_document_version_counters (
+  collection_id uuid NOT NULL REFERENCES stackbone_platform.rag_collections (id) ON DELETE CASCADE,
+  document_key text NOT NULL,
+  last_version integer NOT NULL,
+  PRIMARY KEY (collection_id, document_key)
+);
+
+-- A document from before this starts from the highest version it still holds:
+-- a number deleted before 0095 cannot be told apart from one never handed out.
+INSERT INTO stackbone_platform.rag_document_version_counters (collection_id, document_key, last_version)
+SELECT collection_id, document_key, max(version)
+FROM stackbone_platform.rag_documents
+GROUP BY collection_id, document_key
+ON CONFLICT (collection_id, document_key) DO NOTHING;