@stackbone/cli 0.4.0-alpha.0 → 0.4.1

package/migrations/0056_trigger_subscriptions_scope.sql

@@ -0,0 +1,20 @@
+-- 0056_trigger_subscriptions_scope.sql — the per-subscription values a trigger
+-- declares in `scopeParams`, stored as one jsonb map keyed by the arg each value
+-- is written into (GitHub's `commit-pushed`: `owner`, `repo`, `sha`).
+--
+-- Why a new column instead of reusing `mailbox` (0022): the mailbox is ONE string
+-- and names ONE arg. GitHub's commit list needs three values, and folding them
+-- into `stackbone/stackbone:next` would leave a column called `mailbox` holding a
+-- repository — a lie every later reader pays for. `mailbox` stays exactly as it
+-- is for the Outlook triggers; `scope` is the general form beside it.
+--
+-- Nullable, and no CHECK constraint. 0022's `chk_outlook_app_only_requires_mailbox`
+-- hardcodes one connector id because SQL cannot read a connector definition, and
+-- it already has to be edited whenever another mailbox-scoped connector ships.
+-- Repeating that shape here would mean a migration per connector. The source of
+-- truth is the descriptor's `scopeParams`, enforced where it can actually be read:
+-- the register endpoint rejects a link missing a required value, and the poll
+-- engine throws rather than sending a request with an unsubstituted path.
+
+ALTER TABLE stackbone_platform.trigger_subscriptions
+ADD COLUMN scope jsonb;

package/migrations/0057_trigger_subscriptions_fold_mailbox_into_scope.sql

@@ -0,0 +1,35 @@
+-- 0057_trigger_subscriptions_fold_mailbox_into_scope.sql — retire `mailbox` (0022)
+-- into `scope` (0056).
+--
+-- Both columns hold the same idea: a value the LINK owns, injected into a list arg
+-- on every poll. `mailbox` holds one string and names one arg (Outlook app-only's
+-- `user-id`); `scope` holds a map and names any number (GitHub's `owner`, `repo`,
+-- `sha`). The second is strictly the general case of the first, so keeping both
+-- meant parallel plumbing in six places and a guess for the next scoped connector
+-- about which one to use.
+--
+-- The COPY comes first and the DROP second, in one transaction, because an Outlook
+-- link armed before this migration has to keep polling the same mailbox after it.
+-- `user-id` is the key, not `mailbox`: the key IS the arg the value is written
+-- into, which is what makes the map generic. It matches the `scopeParams` entry the
+-- Outlook trigger now declares.
+--
+-- `scope IS NULL` guards the copy. Nothing writes both columns today, but a row
+-- that already carries its own scope must not lose it to a stale mailbox.
+
+UPDATE stackbone_platform.trigger_subscriptions
+SET scope = jsonb_build_object('user-id', mailbox)
+WHERE mailbox IS NOT NULL
+  AND scope IS NULL;
+
+-- The CHECK goes with the column. It hardcoded `outlook-app-only` because SQL
+-- cannot read a connector definition, so it had to be edited every time a
+-- mailbox-scoped connector shipped. There is deliberately no `scope` equivalent:
+-- the rule lives where the declaration is readable — the register endpoint rejects
+-- a link missing a required value, and the poll engine throws rather than sending a
+-- request with an unsubstituted path.
+ALTER TABLE stackbone_platform.trigger_subscriptions
+DROP CONSTRAINT IF EXISTS chk_outlook_app_only_requires_mailbox;
+
+ALTER TABLE stackbone_platform.trigger_subscriptions
+DROP COLUMN mailbox;

package/migrations/0058_trigger_subscriptions_cursor_column.sql

@@ -0,0 +1,9 @@
+-- 0058_trigger_subscriptions_cursor_column.sql — the column the poll cursor
+-- advances on (PLA-888). For a trigger whose descriptor declares `cursorColumn`
+-- (Supabase's row-inserted), the OPERATOR chooses which column orders the rows —
+-- the generated document carries no constraint metadata, so nothing could
+-- honestly detect one. NULL = the descriptor's own default (`id`); every
+-- pre-existing subscription keeps exactly the behaviour it had.
+
+ALTER TABLE stackbone_platform.trigger_subscriptions
+ADD COLUMN cursor_column text;

package/migrations/0059_trigger_subscriptions_last_error.sql

@@ -0,0 +1,26 @@
+-- 0059_trigger_subscriptions_last_error.sql — a link that cannot poll stops
+-- reading as healthy (PLA-1095).
+--
+-- Before this the row had nowhere to put a failure: the whole shape was id,
+-- connector, trigger_id, principal_key, workflow_name, mapping, enabled,
+-- poll_cursor, remote_subscription_id, last_polled_at, created_at, updated_at,
+-- mailbox, mapping_graph, correlation_key, cursor_column. A revoked connection
+-- made every tick fail forever and the only trace was one stdout line per tick.
+--
+-- `last_polled_at` is deliberately NOT touched. It means "the last poll that
+-- CLOSED", and that is the honest answer to "when was this data last really
+-- read". Making it advance on failed attempts too would turn it into "last
+-- attempt" and a broken link would keep reading fresh — the same lie with a
+-- better alibi. The pair is what disambiguates: polled at 07:48, failing since
+-- 07:49.
+--
+-- All three are nullable / defaulted so every existing row is born healthy and
+-- behaves exactly as it did.
+
+ALTER TABLE stackbone_platform.trigger_subscriptions
+ADD COLUMN last_error text,
+ADD COLUMN last_error_at timestamptz,
+-- The counter is what separates "one blip on a flaky network" from "broken since
+-- Tuesday". Without it a screen can only ever say "failing", and a single
+-- transient failure would read as loudly as a fortnight of them.
+ADD COLUMN consecutive_failures integer NOT NULL DEFAULT 0;

package/migrations/0060_trigger_subscriptions_capped_state.sql

@@ -0,0 +1,39 @@
+-- 0060_trigger_subscriptions_capped_state.sql — a link that hits the per-tick
+-- delivery ceiling on every tick stops reading as healthy (PLA-1213).
+--
+-- PLA-1210 gave the intake a ceiling: a tick forwards at most
+-- `DEFAULT_MAX_DELIVERIES_PER_TICK` new deliveries and, on overflow, re-saves the
+-- cursor it POLLED WITH so the next tick re-polls the same window. That bounds a
+-- runaway burst, and it terminates, because the delivered prefix comes back as
+-- `duplicate` and spends no ceiling.
+--
+-- What it does not do is say anything. The overflow lives in the tick's returned
+-- outcome and in one stdout line; the ROW is written by `saveCursor`, which
+-- clears `last_error`, zeroes `consecutive_failures` and stamps `last_polled_at`.
+-- So a link whose new-item rate exceeds the ceiling — exactly the self-retriggering
+-- case the ceiling was written for — holds its cursor forever while its row renders
+-- as a link that just polled cleanly. The runaway went from loud to silent.
+--
+-- The trio mirrors 0059's failure trio deliberately, and for the same reasons:
+--
+--   * `last_capped_at` pairs with `last_polled_at` the way `last_error_at` does.
+--     Polled at 07:48, capping since 07:49 is the sentence an operator needs.
+--   * `last_deferred_count` is how many items the tick left behind. One number
+--     separates "203 arrived, 3 waited" from "5000 arrived and this will run for
+--     25 ticks", and those want different answers.
+--   * `consecutive_capped_ticks` separates an arming backfill — which caps for
+--     one or two ticks and is the ceiling working as designed — from a link that
+--     has been capping since Tuesday. Without it a screen can only say "capping",
+--     and the backfill would read as loudly as the runaway.
+--
+-- Cleared rather than kept on an uncapped tick, same bargain as `last_error`: the
+-- row means CURRENT state, and a link that has stopped capping must not read as
+-- capping. The history of laps lives in `trigger_deliveries`.
+--
+-- All three are nullable / defaulted, so every existing row is born uncapped and
+-- behaves exactly as it did.
+
+ALTER TABLE stackbone_platform.trigger_subscriptions
+ADD COLUMN last_capped_at timestamptz,
+ADD COLUMN last_deferred_count integer,
+ADD COLUMN consecutive_capped_ticks integer NOT NULL DEFAULT 0;

package/migrations/0061_trigger_subscriptions_cursor_held.sql

@@ -0,0 +1,35 @@
+-- 0061_trigger_subscriptions_cursor_held.sql — `poll_cursor IS NULL` stops
+-- meaning two different things (PLA-1215).
+--
+-- The overload. `poll_cursor = NULL` used to mean exactly one thing, "this link
+-- has never polled", and one write depends on that: `seedCursorIfUnset` arms a
+-- link "from now" with
+--
+--     poll_cursor = COALESCE(poll_cursor, $seed)
+--
+-- so a link that HAS polled resumes where it left off instead of replaying, and a
+-- link whose scope changed (PLA-1144 clears the cursor deliberately) gets a fresh
+-- bookmark. Both correct.
+--
+-- PLA-1210's ceiling added a third case. When a provider rejects a stale opaque
+-- cursor the tick re-polls with `null`, and if THAT window is over the ceiling the
+-- tick holds the cursor it polled with — which is `null`. So a link with a known
+-- multi-tick backlog now sits at NULL, and the COALESCE above cannot tell it from
+-- never-polled: any patch that arms or re-arms the link mid-drain seeds it "from
+-- now" and every deferred item is dropped, silently. That is PLA-1005 through a
+-- different door.
+--
+-- Why a column of its own rather than reading PLA-1213's `consecutive_capped_ticks`,
+-- which is NULL-vs-held information too: the two want opposite clearing rules.
+-- The capped trio is observability ABOUT THE LINK and 0060 clears it when a link is
+-- armed, because a link being armed has not capped yet. This is a fact ABOUT THE
+-- CURSOR and must survive arming — otherwise arming twice reads a cleared counter
+-- the second time and seeds over the backlog anyway, which is the bug with an extra
+-- step.
+--
+-- Written by the same `saveCursor` statement that saves the cursor, so the flag and
+-- the value it describes can never disagree. `false` for every existing row, which
+-- is what they all are: nothing has held a cursor before this ships.
+
+ALTER TABLE stackbone_platform.trigger_subscriptions
+ADD COLUMN poll_cursor_held boolean NOT NULL DEFAULT false;

package/migrations/0062_trigger_deliveries_retention.sql

@@ -0,0 +1,40 @@
+-- 0062_trigger_deliveries_retention.sql — the delivery journal gets a retention
+-- sweep, and the two things an hourly DELETE by age needs on this table (PLA-1209).
+--
+-- `trigger_deliveries` is the at-least-once dedup journal (0021): one row per
+-- `(subscription_id, provider_item_id)`, claimed with an INSERT that collapses on
+-- the unique pair. Nothing pruned it by age. That was fine while every trigger was
+-- creation-shaped — one row per message, per file, per commit — so the table
+-- settled. PLA-878's `dedup.versionPath` (Linear `issue-updated`) keys a row per
+-- CHANGE to an object, and the table stopped being finite on the very index the
+-- dedup reads.
+--
+-- The sweep itself lives in the runtime (`delivery-journal-retention-job.ts`),
+-- on the log-retention job's cadence pattern. This migration is only what the
+-- sweep needs from the schema:
+--
+--   * An index on `created_at`. The age pass deletes `WHERE created_at < cutoff`
+--     in bounded batches, hourly, and without an index every one of those
+--     batches is a sequential scan of a table whose whole problem is its size.
+--     The budget pass reads the same index: it takes ONE subscription's oldest
+--     rows first (`ORDER BY created_at`), and the subscription over budget is by
+--     definition the one holding most of the old rows, so the ascending scan
+--     finds them at the front. No `(subscription_id, created_at)` index on top:
+--     a third index is paid for on every claim, and the dedup index's
+--     `subscription_id` prefix already answers the per-link count.
+--
+--   * Per-table autovacuum, for the reason 0051 gives the log table: the cluster
+--     default waits for dead tuples to reach 20% of the table, and this is now a
+--     table that is bulk-deleted on a schedule. Left on the defaults, an hourly
+--     sweep leaves its dead rows in place for hours under the unique index every
+--     claim probes. The threshold is lower than the log table's because the rows
+--     are far fewer: a journal that only ever held a hundred rows should still
+--     vacuum after its first sweep.
+
+CREATE INDEX IF NOT EXISTS trigger_deliveries_created_at_idx
+    ON stackbone_platform.trigger_deliveries (created_at);
+
+ALTER TABLE stackbone_platform.trigger_deliveries SET (
+    autovacuum_vacuum_scale_factor = 0.02,
+    autovacuum_vacuum_threshold = 500
+);

package/migrations/0063_eval_case_results_not_evaluable.sql

@@ -0,0 +1,42 @@
+-- A SEVENTH ENDING: `not_evaluable` (PLA-1228).
+--
+-- A measured run answers its connector calls with stand-ins, and only Outlook has
+-- one. Every other connector is REFUSED rather than passed through to the real
+-- provider — which is the safe choice and stays — but the refusal arrives as an
+-- ordinary failure, so the case ends `errored` and an operator cannot tell "this
+-- workflow is not measurable on this box" from "this workflow is broken".
+--
+-- WHY NOT REUSE `blocked_by_guardrail`. It is the obvious candidate and it is
+-- wrong. That value does not mean "a rule said no"; it means NOTHING RAN. It is
+-- written on one path only — the start path's catch, which throws before anything
+-- is enqueued (`workflow-case-runner.ts`, and `eval-case-runner.ts` says the same
+-- in different words). A connector refusal happens MID-RUN: the workflow started,
+-- and the steps before the refused call may have had effects. Widening the value
+-- would silently falsify it for anything already reading it as "no side effects".
+--
+-- So the vocabulary grows, which the 0042 comment above deliberately made
+-- expensive. This is the case that pays for it: `escalated` and `asked_user` were
+-- kept apart because folding them made the pause criteria unmeasurable, and the
+-- same test applies here — an operator's next action after "not measurable here"
+-- (register a stand-in, or measure something else) is not the action after
+-- "errored" (read the trace, fix the workflow).
+--
+-- NULLABLE and never backfilled, for the same reason as 0042: the table is
+-- append-only and every row already in it belongs to a sealed run. A case that
+-- ended `errored` because of a missing stand-in stays `errored`, because that is
+-- what was recorded and there is no honest way to tell those rows apart now.
+
+ALTER TABLE stackbone_platform.eval_case_results
+    DROP CONSTRAINT IF EXISTS eval_case_results_ended_check;
+
+ALTER TABLE stackbone_platform.eval_case_results
+    ADD CONSTRAINT eval_case_results_ended_check
+    CHECK (ended IS NULL OR ended IN (
+        'completed',
+        'escalated',
+        'asked_user',
+        'blocked_by_guardrail',
+        'not_evaluable',
+        'errored',
+        'cancelled'
+    ));

package/migrations/0064_workflow_file_outputs.sql

@@ -0,0 +1,90 @@
+-- 0064_workflow_file_outputs.sql — where a workflow's declared file outputs go,
+-- and where a document waits when they cannot (PLA-1092 slices 3 and 4).
+--
+-- Before this there was no table at all. A workflow declares
+-- `export const fileOutputs = ['prd']` and the boot manifest carries the names
+-- (slice 1); `drive.file-write` knows how to file a document into a Drive folder
+-- (slice 2); and nothing on the box connected the two. The creator's code named
+-- a folder id, a connector and a principal in the workflow body, and moving the
+-- output meant a redeploy.
+--
+-- Two tables, and they are deliberately not one.
+--
+-- `workflow_file_output_bindings` is the OPERATOR's decision: this output of this
+-- workflow lands THERE, through THAT connection. One row per (workflow, output),
+-- which is what the UNIQUE says — a second binding for the same output is an
+-- edit of the first, never a sibling.
+--
+--   `destination jsonb`, not `folder_id text`. Only the writer knows what its
+--   provider calls a destination — a Drive folder id today, a Notion page or an
+--   S3 prefix tomorrow — and `FileWriteRequest.destination` is documented
+--   opaque for exactly that reason. Naming the column after one provider's noun
+--   is the `mailbox` column 0056 argued against, one table over. The one rule
+--   the box holds it to lives in code (`file-output-writer.ts`): the object
+--   carries an `id` string, and that string is what the writer receives.
+--
+--   No `installation_id`. Every read here is `WHERE id = $1` or by the
+--   (workflow, output) pair: one box is one installation, and the box's own
+--   database is the scope — the same reason `trigger_subscriptions` carries none.
+--
+-- `parked_file_outputs` is the DOCUMENT that could not be filed. By the time a
+-- run reaches its output the expensive work is done — the model has run, the
+-- bytes are staged — so a missing binding, or a provider that said no, must not
+-- throw the document away. The row keeps the staged key and everything needed
+-- to file it later; a drain (slice 5, not here) reads it back.
+--
+--   `reason` is `'unbound' | 'write_failed'`, text with no CHECK. 0056's rule:
+--   SQL cannot read a connector definition, and a constraint that needs one
+--   lives in code. `unbound` says nobody decided where this goes yet;
+--   `write_failed` says somebody did and the provider refused.
+--
+--   `last_error` / `last_error_at` / `attempts` are lifted from 0059 for its own
+--   reason: a counter is what separates one blip from broken-since-Tuesday, and
+--   a screen without it can only ever say "failing". `attempts` is incremented
+--   in SQL by the store, never read-then-written, so two drains racing on one
+--   row cannot both write 1.
+--
+--   `filed_file_id` is the row's terminal state: `NULL` while it waits, the
+--   provider's id once a later attempt landed it. The row is KEPT rather than
+--   deleted on success, so an operator can still answer "where did that PRD
+--   from Tuesday end up" after the fact.
+--
+-- Indexes: one partial index on the parked table. The only list read is "what
+-- is still waiting", newest first — `WHERE filed_file_id IS NULL ORDER BY
+-- created_at DESC` — and a filed row is never listed again, so indexing only
+-- the unfiled ones keeps the index the size of the backlog rather than of the
+-- history. The bindings table needs nothing beyond its UNIQUE: the write path
+-- reads exactly by that pair, and the id reads hit the primary key.
+
+CREATE TABLE stackbone_platform.workflow_file_output_bindings (
+    id            uuid        PRIMARY KEY,
+    workflow_name text        NOT NULL,
+    output_name   text        NOT NULL,
+    connector     text        NOT NULL,
+    principal_key text        NOT NULL,
+    destination   jsonb       NOT NULL,
+    created_at    timestamptz NOT NULL DEFAULT now(),
+    updated_at    timestamptz NOT NULL DEFAULT now(),
+    UNIQUE (workflow_name, output_name)
+);
+
+CREATE TABLE stackbone_platform.parked_file_outputs (
+    id            uuid        PRIMARY KEY,
+    workflow_name text        NOT NULL,
+    output_name   text        NOT NULL,
+    run_id        text,
+    file_name     text        NOT NULL,
+    storage_key   text        NOT NULL,
+    content_type  text        NOT NULL,
+    reason        text        NOT NULL,
+    last_error    text,
+    last_error_at timestamptz,
+    attempts      integer     NOT NULL DEFAULT 0,
+    filed_file_id text,
+    created_at    timestamptz NOT NULL DEFAULT now(),
+    updated_at    timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX parked_file_outputs_waiting_idx
+    ON stackbone_platform.parked_file_outputs (created_at DESC)
+    WHERE filed_file_id IS NULL;

package/migrations/0065_parked_file_outputs_filing_claim.sql

@@ -0,0 +1,36 @@
+-- 0065_parked_file_outputs_filing_claim.sql — make "this row is being filed"
+-- a fact Postgres holds, not one node believed (PLA-1092 slice 5).
+--
+-- The drain read the row, saw `filed_file_id IS NULL`, spent a few hundred
+-- milliseconds at the provider, and only then wrote the id back with an
+-- unconditional UPDATE. Nothing claimed the row in between, so two drains 200 ms
+-- apart both passed the check, both filed, and both marked: two documents in the
+-- operator's folder, one `filed_file_id` overwriting the other, and the orphaned
+-- id recorded nowhere. The comment above the guard named "a double click" as the
+-- exact case it prevented, which is what a read-then-act guard cannot do.
+--
+-- `filing_claimed_at` is that claim. One UPDATE takes it — `WHERE filed_file_id
+-- IS NULL AND (filing_claimed_at IS NULL OR filing_claimed_at < <stale>)` — and
+-- its row count is the answer: the loser never reaches the provider.
+--
+-- WHY A COLUMN AND NOT `filed_file_id` ITSELF. The claim has to be taken BEFORE
+-- the provider call, and before the provider call there is no file id to write.
+-- Writing a sentinel into the column that means "landed here" would make the
+-- terminal state unreadable, and `listParked`'s partial index is built on it.
+--
+-- WHY IT EXPIRES. A box that dies between the claim and the release would
+-- otherwise leave the row claimed forever and the button dead forever, with no
+-- way out but SQL. The staleness window is the writer's
+-- (`FILING_CLAIM_TTL_MS`), not a CHECK here: the number is a judgement about how
+-- long a provider round-trip can take, and that belongs beside the code that
+-- makes it. Retaking a stale claim can still file a second copy — a claim is not
+-- an idempotency record — but it bounds that to a box that crashed mid-write
+-- rather than to a double click.
+--
+-- Nullable, no default, no backfill: an existing parked row is by definition not
+-- being filed right now, and NULL says exactly that. The partial index from 0064
+-- is untouched — every read that uses it still filters on `filed_file_id IS
+-- NULL`, and the claim is only ever read by id.
+
+ALTER TABLE stackbone_platform.parked_file_outputs
+    ADD COLUMN filing_claimed_at timestamptz;

package/migrations/0066_filed_file_outputs.sql

@@ -0,0 +1,70 @@
+-- 0066_filed_file_outputs.sql — a file output that SUCCEEDED leaves a record, so
+-- the retry after a lost response does not file a second copy (PLA-1247 slice 1).
+--
+-- 0064 recorded only the documents that could NOT be filed. The success path was
+-- write-only by decision: `file-output-writer.ts` said "nothing is recorded here:
+-- the run's own timeline already says a document went out". That holds exactly as
+-- long as the response arrives.
+--
+-- When it does not — the box restarts between the writer returning and `c.json`,
+-- a proxy times out, a connection resets — the SDK's `fetch` throws, the step
+-- fails, and the durable step retries. The retry stages fresh bytes under a fresh
+-- uuid and files again, and `drive.files.create` is not idempotent: two identical
+-- documents in the customer's folder, with nothing on either side able to say the
+-- first one landed. The create-then-fill order 0064's writers use exists to stop
+-- a crash leaving a confusing artefact; a lost response reintroduced it through
+-- the front door.
+--
+-- THE KEY IS THE PRIMARY KEY. `(run_id, workflow_name, output_name)` is the
+-- identity of "this run already filed this output", so it is the row's identity
+-- too — there is no surrogate uuid, because no second row for that triple is ever
+-- meaningful and a surrogate id would be a second way to name the same fact. A
+-- repeat write reads it and answers the recorded `file_id` without touching the
+-- provider.
+--
+-- WHY NOT `parked_file_outputs`. That table holds one row per FAILED ATTEMPT and
+-- carries no unique key on the triple, deliberately: a run that parks `unbound`
+-- and is then retried parks again, and both rows are real. Adding the unique key
+-- an idempotency record needs would refuse the second park — turning a lost
+-- document into a lost document AND a failed insert. Nor is 0065's
+-- `filing_claimed_at` this record: a claim has a TTL so a dead box cannot hold a
+-- row forever, and a retaken stale claim can still file a second copy. A claim
+-- bounds a duplicate; only a recorded file id removes one.
+--
+-- `run_id` IS `NOT NULL`, and that is the whole statement of what happens without
+-- one. `parked_file_outputs.run_id` is nullable because a parked document is worth
+-- keeping whether or not a run claimed it; an idempotency key with a null
+-- component is not a key. A write carrying no run id is not deduped at all — see
+-- `file-output-writer.ts`, which decides that in code rather than discovering it
+-- here as a constraint violation. Collapsing every run-less write of one output
+-- into a single row would short-circuit the SECOND real document and never file
+-- it, which is worse than the duplicate this table exists to prevent.
+--
+-- `file_name` and `storage_key` ride along for the audit question 0064 opened and
+-- answered only for the failed half: "where did Tuesday's PRD end up". Without
+-- them a filed row names a provider id and nothing a human recognises.
+--
+-- RETENTION: none, on purpose, and this is the paragraph 0062 earned. The
+-- delivery journal needed a sweep because its key space grew with provider
+-- CHATTER — one row per observed change, most of which produce no work — with no
+-- ceiling on an index every claim probes. This table grows one row per document
+-- that actually exists in a customer's folder: the row count IS the folder count,
+-- there is no amplification, and a workspace with enough rows here to notice has
+-- a filing problem long before it has a table problem. Every read is a point
+-- lookup on the primary key, so size costs nothing at read time, and the row is
+-- the only surviving answer to where a filed document went — deleting it by age
+-- would make the SUCCESSFUL half less answerable than the parked half 0064 keeps
+-- forever. If a workspace ever files at machine cadence, the age + budget sweep in
+-- `delivery-journal-retention-job.ts` is the shape to copy, and it would want an
+-- index on `filed_at` that is deliberately not paid for here.
+
+CREATE TABLE stackbone_platform.filed_file_outputs (
+    run_id        text        NOT NULL,
+    workflow_name text        NOT NULL,
+    output_name   text        NOT NULL,
+    file_id       text        NOT NULL,
+    file_name     text        NOT NULL,
+    storage_key   text        NOT NULL,
+    filed_at      timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (run_id, workflow_name, output_name)
+);

package/migrations/0067_parked_outputs_carry_a_kind.sql

@@ -0,0 +1,72 @@
+-- 0067_parked_outputs_carry_a_kind.sql — what waits on the parked list can now
+-- be a call as well as a document (PLA-1253).
+--
+-- 0064 built `parked_file_outputs` around one thing: a document the run already
+-- produced, kept by its staged key so a missing binding could not throw it away.
+-- An action parks for the same reason and keeps something different. It has no
+-- bytes. What has to survive is the ARGUMENT OBJECT the run composed, because
+-- recomputing it means re-running the whole workflow — the model call included.
+--
+-- ONE TABLE, NOT TWO. The operator's question is "what has not gone out yet",
+-- and it is one question. A second table would mean two lists to merge, two
+-- claims, two partial indexes and two drains, for two rows that differ in three
+-- columns. The screen renders each as its own kind; the storage does not have to.
+--
+-- The table KEEPS ITS NAME for the reason 0064's siblings kept theirs (PLA-1250):
+-- renaming a table is a migration plus a version bump for a gain nobody outside
+-- this repo sees, and the store carries a comment explaining the mismatch.
+--
+-- `kind` DEFAULTS to 'file' and every existing row is one. No CHECK, following
+-- 0064's rule for `reason`: the set of kinds is declared in the manifest a box
+-- boots with, and SQL cannot read it.
+--
+-- THE THREE FILE COLUMNS LOSE THEIR NOT NULL. `file_name`, `storage_key` and
+-- `content_type` describe a document, and an action has none of them. Dropping
+-- the constraint is what makes one table honest rather than one table with three
+-- empty strings pretending to be a filename. The code holds what SQL now cannot:
+-- the writer only ever reads them on a `kind = 'file'` row.
+--
+-- `settled_at` IS THE NEW TERMINAL STATE, AND IT REPLACES A PREDICATE RATHER
+-- THAN ADDING ONE. 0064 made `filed_file_id` the terminal state — NULL while it
+-- waits, the provider's id once it landed — and 0065 argued in writing why a
+-- sentinel must never be written into it: "writing a sentinel into the column
+-- that means 'landed here' would make the terminal state unreadable, and
+-- `listParked`'s partial index is built on it." That argument holds for an
+-- action, which has no file id to write and may have no id at all: an operation
+-- can answer a list, a boolean, or nothing.
+--
+-- So the two facts are separated. `filed_file_id` goes back to being ONLY the
+-- file's payload; `settled_at` is "this row is done", for both kinds, and it is
+-- the single predicate the claim, the update and the list now share. The
+-- alternative — `filed_file_id IS NULL AND fired_at IS NULL` — encodes one
+-- concept in two columns and makes every future reader hold both.
+--
+-- The BACKFILL is `updated_at`, and it is approximate on purpose. A row filed
+-- before this migration has no record of the instant it landed; its last write
+-- is the closest true thing, and nothing reads `settled_at` as a moment — every
+-- read is `IS NULL`. Saying so here is cheaper than a column that looks precise
+-- and is not.
+
+ALTER TABLE stackbone_platform.parked_file_outputs
+    ADD COLUMN kind       text NOT NULL DEFAULT 'file',
+    ADD COLUMN operation  text,
+    ADD COLUMN args       jsonb,
+    ADD COLUMN settled_at timestamptz;
+
+ALTER TABLE stackbone_platform.parked_file_outputs
+    ALTER COLUMN file_name    DROP NOT NULL,
+    ALTER COLUMN storage_key  DROP NOT NULL,
+    ALTER COLUMN content_type DROP NOT NULL;
+
+UPDATE stackbone_platform.parked_file_outputs
+   SET settled_at = updated_at
+ WHERE filed_file_id IS NOT NULL;
+
+-- The waiting list, on the predicate both kinds share. Dropped and recreated
+-- rather than left beside a new one: two partial indexes over the same rows on
+-- two spellings of "still waiting" is how the two spellings drift apart.
+DROP INDEX IF EXISTS stackbone_platform.parked_file_outputs_waiting_idx;
+
+CREATE INDEX parked_file_outputs_waiting_idx
+    ON stackbone_platform.parked_file_outputs (created_at DESC)
+    WHERE settled_at IS NULL;

package/migrations/0068_poll_revision_and_delivery_last_seen.sql

@@ -0,0 +1,12 @@
+-- Fence poll results against operator edits without holding transactions over provider I/O.
+ALTER TABLE stackbone_platform.trigger_subscriptions
+  ADD COLUMN poll_revision bigint NOT NULL DEFAULT 0;
+
+-- Existing claims get a full retention grace period from migration time.
+-- Encountering a duplicate refreshes this timestamp without changing its delivery history.
+ALTER TABLE stackbone_platform.trigger_deliveries
+  ADD COLUMN last_seen_at timestamptz NOT NULL DEFAULT now();
+CREATE INDEX trigger_deliveries_last_seen_at_idx
+  ON stackbone_platform.trigger_deliveries (last_seen_at);
+CREATE INDEX trigger_deliveries_subscription_last_seen_at_idx
+  ON stackbone_platform.trigger_deliveries (subscription_id, last_seen_at);

package/migrations/0069_trigger_deliveries_queued_and_starting_status.sql

@@ -0,0 +1,50 @@
+-- 0069_trigger_deliveries_queued_and_starting_status.sql — give `claimed` back its
+-- literal meaning of "claimed and never attempted", so an abandoned claim can be
+-- told apart from a live one and released (PLA-1358).
+--
+-- THE BUG. The inbound forwarder claims the (subscription, provider item) delivery
+-- BEFORE it maps or starts anything. A process that dies in that gap leaves a
+-- `claimed` row with no run; the next poll's claim collapses on the dedup index,
+-- the tick counts a duplicate, and the cursor advances past an event that never
+-- started. A sweep that released old `claimed` rows would fix it — except that
+-- today three different situations all leave exactly `status = 'claimed'`,
+-- `run_id` NULL, and nothing in the row separates them:
+--
+--   1. the abandoned claim (a crash between the claim and the start)
+--   2. a delivery durably ENQUEUED behind an active serial run — accepted, no run
+--      yet, deliberately not marked started so it never presents a run that does
+--      not exist
+--   3. a run that DID start whose best-effort `markStarted` write was swallowed
+--
+-- Releasing (2) re-delivers an item that is already queued to run; releasing (3)
+-- runs the customer's workflow a second time. Age does not separate them either.
+-- So the journal gains two statuses and `claimed` stops being ambiguous:
+--
+--   `starting` — written immediately BEFORE the forwarder calls start or resume.
+--                A row still `claimed` therefore provably never reached either,
+--                which is what makes case 3 impossible and the sweep safe.
+--   `queued`   — case 2, labelled instead of left claimed. Still no `run_id`: the
+--                real run surfaces on its own when the serial gate admits it.
+--
+-- The 0021 CHECK was declared INLINE (unnamed), so Postgres system-named it
+-- `trigger_deliveries_status_check`; 0027 dropped that and re-added it with
+-- `resumed`. Same move here, carrying the WHOLE accepted set forward — a widening
+-- that re-derives the list instead of carrying it drops a status the forwarder
+-- still writes, and the resulting constraint violation is swallowed by the
+-- best-effort journal write, so it surfaces as a mislabelled row and not an error.
+--
+-- ONE-TIME COST ON DEPLOY, RECORDED AND ACCEPTED. Every `claimed` row that
+-- predates this migration is ambiguous by construction — that is the bug — and
+-- nothing in the row can say which of the three cases it was. The reclaim sweep
+-- releases them like any other row. So an item that was sitting in a World serial
+-- queue from before this migration can run once from that queue and once from the
+-- re-delivery. It is bounded: one time, only `serial` workflows, only queues older
+-- than the sweep's threshold, and only where the cursor has not already advanced
+-- past the item. The alternative — a predicate skipping rows older than this
+-- migration — would permanently forfeit recovery for exactly the rows most likely
+-- to be abandoned, so it was rejected deliberately.
+ALTER TABLE stackbone_platform.trigger_deliveries
+    DROP CONSTRAINT IF EXISTS trigger_deliveries_status_check;
+ALTER TABLE stackbone_platform.trigger_deliveries
+    ADD CONSTRAINT trigger_deliveries_status_check
+    CHECK (status IN ('claimed', 'started', 'resumed', 'rejected', 'queued', 'starting'));

package/migrations/0070_trigger_deliveries_takeover_count.sql

@@ -0,0 +1,39 @@
+-- 0070_trigger_deliveries_takeover_count.sql — bound the poison item the cursor
+-- hold creates: count how many times a delivery's abandoned claim has been taken
+-- over, so the caller can stop taking it over (PLA-1380).
+--
+-- THE REGRESSION THIS BOUNDS. 0069 plus the in-`claim` takeover made an abandoned
+-- claim recoverable by the next poll, and the intake tick now HOLDS ITS CURSOR
+-- while a duplicate lands on a row still `claimed`. For an item whose forward
+-- kills the process that combination never ends:
+--
+--   1. `claim` takes the aged row over and re-stamps `created_at`, so the hourly
+--      `releaseAbandonedClaims` (15 min on `created_at`) never matches it.
+--   2. Every re-list refreshes `last_seen_at`, so `deleteDeliveriesOlderThan`
+--      never ages it out.
+--   3. The tick holds its cursor, so every item BEHIND this one is blocked too.
+--   4. The forward kills the process again on the next takeover. Forever, once
+--      per takeover interval.
+--
+-- Nothing in the row could break that: age cannot, because a takeover resets it,
+-- and that reset is load-bearing (it is what stops two forwarders in one drain
+-- loop from both taking the same row over). So the row gains a counter that only
+-- moves forward. `claim` increments it inside the SAME `CASE` that re-stamps
+-- `created_at`, so it advances on an actual takeover and never on a duplicate or
+-- a fresh insert, and the CALLER refuses to forward past
+-- `DELIVERY_CLAIM_MAX_TAKEOVERS` — journalling the row `rejected` with reason
+-- `claim_abandoned`, which is terminal, so the poll after it reads a plain
+-- `duplicate` and the cursor finally advances.
+--
+-- NO CHECK REBUILD. The abandonment reuses `rejected` rather than minting a
+-- status, so `trigger_deliveries_status_check` (re-added by 0069) stands as is.
+--
+-- NO TABLE REWRITE. `ADD COLUMN ... NOT NULL DEFAULT <constant>` is metadata-only
+-- since PostgreSQL 11: the default is recorded in the catalog and read for
+-- existing rows instead of being written into each one. It takes an ACCESS
+-- EXCLUSIVE lock for the catalog update and releases it immediately, so the cost
+-- is the lock wait behind whatever else is touching the table, not a rewrite of
+-- it. Existing rows read 0, which is the honest value — nothing counted their
+-- takeovers before this migration, so they get the full budget from here.
+ALTER TABLE stackbone_platform.trigger_deliveries
+  ADD COLUMN takeover_count integer NOT NULL DEFAULT 0;