@stackbone/cli 0.5.4 → 0.6.0

package/migrations/0073_model_selections.sql

@@ -0,0 +1,38 @@
+-- 0073_model_selections.sql — the model an operator picked for one key of one
+-- deep agent or one workflow (PLA-1599, ADR 2026-09-17 D1).
+--
+-- A MODEL SELECTION is one model id per (owner, key), stored per box. Staging
+-- and production can run different models, so there is no per-organization or
+-- per-template row.
+--
+-- NO VERSIONS, unlike `prompts` (0047/0048). A prompt is text someone writes and
+-- reviews; a selection is one id. A write replaces the row and a reset deletes
+-- it, so "no row" means "no pick" and the code default applies. The activity
+-- log records who changed it and when (`model_selection.update` /
+-- `model_selection.delete`), which is the history this table does not keep.
+--
+-- Identity is (owner_kind, owner_name, key), the vocabulary 0047 uses for a
+-- prompt's owner, and for the same reason: two workflows may each declare a
+-- `chat` key and run different models under it.
+--
+-- Deliberately NO CHECK on `owner_kind`, following 0047: a box running an older
+-- build must be able to STORE a kind it cannot resolve. An unrecognised kind
+-- never matches a read, which is the safe failure. `owner_name` is a free string
+-- for the same reason as 0047's.
+--
+-- No catalogue check on `model_id` either. The model provider may be unreachable
+-- while an operator edits, and a wrong id fails at run time with the provider's
+-- own message (ADR D4).
+--
+-- `updated_by` is the acting user's id as the box reads it (a verified identity,
+-- or the control-plane proxy's actor header): free text and nullable, like
+-- `workspace_settings.updated_by` (0029). A `stackbone dev` write names nobody.
+CREATE TABLE IF NOT EXISTS stackbone_platform.model_selections (
+    owner_kind  text        NOT NULL,
+    owner_name  text        NOT NULL,
+    key         text        NOT NULL,
+    model_id    text        NOT NULL,
+    updated_by  text,
+    updated_at  timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (owner_kind, owner_name, key)
+);

package/migrations/0074_runs_cancelled_status.sql

@@ -0,0 +1,18 @@
+-- 0074_runs_cancelled_status.sql — a status of its own for a run an operator
+-- cancelled (PLA-1716, PRD PLA-1685).
+--
+-- Until now the cancel wrote `interrupted`, the status a run parked on a human
+-- decision also carries, so the row could not say which of the two it was: the
+-- Runs screen showed both the same, the delete policy had to refuse both, and
+-- the reconcile sweep reopened a cancelled workflow run to `running` because it
+-- read as a pause. `cancelled` is final — nothing that happens after it reopens
+-- or completes the run — and the box store enforces that with a guard on every
+-- close.
+--
+-- Widen `runs_status_check` to match `runStatusSchema`, the same way 0023 added
+-- `waiting`. No trigger change: `notify_run_event` (0001) already emits
+-- `run.finished` with the new status when a cancel stamps `finished_at`.
+ALTER TABLE stackbone_platform.runs DROP CONSTRAINT IF EXISTS runs_status_check;
+ALTER TABLE stackbone_platform.runs
+    ADD CONSTRAINT runs_status_check
+    CHECK (status IN ('running', 'done', 'failed', 'interrupted', 'waiting', 'cancelled'));

package/migrations/0075_runs_trigger_ref.sql

@@ -0,0 +1,41 @@
+-- 0075_runs_trigger_ref.sql — every workflow start gate names itself (PLA-1717,
+-- PRD PLA-1685).
+--
+-- Until now the projector stamped every workflow run `workflow`, whether an
+-- operator started it, a cron tick fired it, or a Connect link delivered the
+-- event behind it: the row is written from the start unit every gate funnels
+-- through, and nothing told that unit which gate called it. Each gate now passes
+-- its trigger explicitly and the projector writes it as given. The trigger is
+-- never guessed from the workflow's name.
+--
+-- Two new values, so the CHECK is recreated with the WHOLE list (a recreated
+-- named CHECK replaces the old one wholesale; see 0038):
+--
+--   - `platform`: a run the box started as its own errand, not the operator's
+--     traffic: rag-ingest, the Auto-map suggestion, an eval judge. The same
+--     starts that already skip the operator's guardrails (`platformInvoked`).
+--   - `unknown`: a start no gate stamped. The honest default, where `workflow`
+--     used to be a guess.
+--
+-- `trigger_ref` says WHICH source started the run when the trigger alone does
+-- not: the `trigger_subscriptions.id` of the Connect link for `event`, NULL for
+-- every other gate. Written once at the start; a resume keeps it (the box store
+-- coalesces it exactly like `trigger`).
+--
+-- NULLABLE, NO DEFAULT, NO BACKFILL. Existing rows keep their `workflow` and a
+-- NULL ref: nothing on them says which gate started them.
+--
+-- NO FOREIGN KEY. A run outlives the link that started it: an operator deleting
+-- a link must neither delete the run history nor be refused because runs exist.
+-- The read-time link join (`trigger_deliveries`) stays the source for the link's
+-- connector and trigger names.
+--
+-- NO INDEX. Nothing filters on it yet; an index would be a write cost with no
+-- reader.
+ALTER TABLE stackbone_platform.runs DROP CONSTRAINT IF EXISTS runs_trigger_check;
+ALTER TABLE stackbone_platform.runs
+    ADD CONSTRAINT runs_trigger_check
+    CHECK (trigger IN ('manual', 'webhook', 'cron', 'event', 'job', 'workflow', 'chat', 'eval', 'platform', 'unknown'));
+
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS trigger_ref text;

package/migrations/0076_event_journal.sql

@@ -0,0 +1,150 @@
+-- 0076_event_journal.sql — the box's event journal (PLA-1718, PRD PLA-1685).
+--
+-- An append-only record of the box's business facts, in a schema of its own:
+--
+--   stores → stackbone_events.outbox → relay → stackbone_events.events
+--
+-- A store writes the domain row and its outbox row in ONE transaction, so both
+-- land or neither does. The relay (`@stackbone/event-journal`) moves committed
+-- outbox rows into `events` once a second and gives each a `position`. Readers
+-- (the Insights engine, later a rollup or an exporter) keep a cursor on
+-- `position`. Nothing here leaves the box.
+--
+-- The second schema these migrations create, and the box's third:
+-- `stackbone_checkpoints` is created by the deep-agent checkpointer at boot. A
+-- DBA who runs with STACKBONE_SKIP_MIGRATIONS=1 applies this file by hand like
+-- every other one in this directory; everything in it is schema-qualified.
+
+CREATE SCHEMA IF NOT EXISTS stackbone_events;
+
+-- event_id: a name-based uuid computed from the event name and its natural key
+-- (the row's id, plus its event_seq when the row can pass through the same
+-- state twice). The same fact written twice gets the same id, and the relay
+-- drops the second copy. Built on md5 so no extension is needed; the version
+-- nibble says 3 (MD5 name-based) and the variant is the RFC one, so any uuid
+-- parser reads it. U+001F separates the two parts so ('a.b', 'c') and
+-- ('a.bc', '') never collide.
+CREATE OR REPLACE FUNCTION stackbone_events.event_uuid(event_name text, natural_key text)
+RETURNS uuid
+LANGUAGE sql
+IMMUTABLE STRICT PARALLEL SAFE
+AS $$
+  SELECT (substr(h, 1, 12) || '3' || substr(h, 14, 3)
+          || substr('89ab89ab89ab89ab', strpos('0123456789abcdef', substr(h, 17, 1)), 1)
+          || substr(h, 18))::uuid
+    FROM (SELECT md5(event_name || chr(31) || natural_key) AS h) AS digest
+$$;
+
+-- The outbox. Its insert rides the domain write, so nothing in it may fail on
+-- data: every envelope column is text, props is jsonb, and there is no CHECK and
+-- no cast. The relay casts on the way out, and a row that does not cast goes to
+-- dead_letters instead of blocking the rest. `id` is the order the relay moves
+-- rows in; `enqueued_at` is what the relay's once-a-minute log line reports the
+-- age of.
+CREATE TABLE IF NOT EXISTS stackbone_events.outbox (
+    id             bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    enqueued_at    timestamptz NOT NULL DEFAULT now(),
+    event_id       text,
+    name           text,
+    version        text,
+    occurred_at    text,
+    recorded_at    text,
+    run_id         text,
+    correlation_id text,
+    causation_id   text,
+    aggregate      text,
+    event_seq      text,
+    entity         text,
+    entity_kind    text,
+    trigger        text,
+    actor          text,
+    channel        text,
+    props          jsonb
+);
+
+-- The journal. `position` orders one box's journal and means nothing outside
+-- it. CACHE 1 on purpose: a sequence that caches hands each backend a private
+-- range, so a relay on a fresh connection could take numbers BELOW rows another
+-- backend already committed, and a reader walking `position` would skip them.
+-- The envelope's run dimensions are columns, so no query needs a join.
+-- `source_id` is not a column: it is one value per box and lives in `meta`.
+CREATE TABLE IF NOT EXISTS stackbone_events.events (
+    position       bigint      GENERATED ALWAYS AS IDENTITY (CACHE 1) PRIMARY KEY,
+    event_id       uuid        NOT NULL,
+    name           text        NOT NULL,
+    version        integer     NOT NULL CHECK (version > 0),
+    occurred_at    timestamptz NOT NULL,
+    recorded_at    timestamptz NOT NULL,
+    run_id         text,
+    correlation_id text,
+    causation_id   text,
+    aggregate      text,
+    event_seq      integer     CHECK (event_seq >= 0),
+    entity         text,
+    entity_kind    text,
+    trigger        text,
+    actor          text,
+    channel        text,
+    props          jsonb       NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(props) = 'object'),
+    CONSTRAINT events_event_id_key UNIQUE (event_id)
+);
+
+CREATE INDEX IF NOT EXISTS events_name_occurred_at_idx
+    ON stackbone_events.events (name, occurred_at);
+
+-- The rows the relay could not move: the outbox row as it was written, and the
+-- error Postgres gave for it. Nothing deletes these, the retention included.
+CREATE TABLE IF NOT EXISTS stackbone_events.dead_letters (
+    id        bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    outbox_id bigint      NOT NULL,
+    payload   jsonb       NOT NULL,
+    error     text        NOT NULL,
+    failed_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- One row per box: the source every event in this journal belongs to. The box
+-- writes it on its first boot — the installation id it resolved, `local-dev`
+-- under `stackbone dev` — and never changes it.
+CREATE TABLE IF NOT EXISTS stackbone_events.meta (
+    singleton  boolean     PRIMARY KEY DEFAULT true CHECK (singleton),
+    source_id  text        NOT NULL,
+    created_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- Append-only. The relay is the journal's ONLY writer and the retention job its
+-- only deleter; each names itself for its own transaction with
+-- `set_config('stackbone_events.writer', 'relay' | 'retention', true)`, and this
+-- statement trigger refuses everything else, UPDATE always. A guard against a
+-- code path that writes the journal by mistake, not a security boundary: the
+-- roles that can reach this table at all are the box's owner and, read-only,
+-- stackbone_viewer.
+CREATE OR REPLACE FUNCTION stackbone_events.events_refuse_foreign_write() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+    writer text := coalesce(current_setting('stackbone_events.writer', true), '');
+BEGIN
+    IF TG_OP = 'INSERT' AND writer = 'relay' THEN
+        RETURN NULL;
+    END IF;
+    IF TG_OP IN ('DELETE', 'TRUNCATE') AND writer = 'retention' THEN
+        RETURN NULL;
+    END IF;
+    RAISE EXCEPTION 'stackbone_events.events is append-only: % refused', TG_OP
+        USING ERRCODE = 'restrict_violation',
+              HINT = 'Only the event relay inserts and only the retention job deletes.';
+END;
+$$;
+
+DROP TRIGGER IF EXISTS events_refuse_foreign_write ON stackbone_events.events;
+CREATE TRIGGER events_refuse_foreign_write
+    BEFORE INSERT OR UPDATE OR DELETE OR TRUNCATE ON stackbone_events.events
+    FOR EACH STATEMENT EXECUTE FUNCTION stackbone_events.events_refuse_foreign_write();
+
+-- stackbone_viewer reads the journal and its meta, and nothing else here. Table
+-- by table and with NO default privileges on the schema, unlike 0005's grants on
+-- `public` and `stackbone_platform`: a table added here later stays closed to the
+-- viewer until a migration opens it. The REVOKE is explicit so a cluster-wide
+-- default privilege a DBA set by hand cannot open the outbox either.
+GRANT USAGE ON SCHEMA stackbone_events TO stackbone_viewer;
+GRANT SELECT ON stackbone_events.events, stackbone_events.meta TO stackbone_viewer;
+REVOKE ALL ON stackbone_events.outbox, stackbone_events.dead_letters FROM stackbone_viewer;

package/migrations/0077_runs_event_seq.sql

@@ -0,0 +1,28 @@
+-- 0077_runs_event_seq.sql — the two columns a run needs to journal its start and
+-- its closes (PLA-1721, PRD PLA-1685).
+--
+-- `event_seq`: how many times this row has closed since it was inserted. 0 when
+-- the row is written, so `run.started` carries 0; each close that changes the
+-- status adds 1, and `run.finished` carries the new value. A close on a row whose
+-- `event_seq` is already above 0 is a second close (the reconciler failed the
+-- run, then it completed), journaled with `reclose = true`. Together with the
+-- row's `created_at` it keys the event: a run id deleted and written again starts
+-- back at 0, and `created_at` tells the two rows apart.
+--
+-- `waited_for_approval`: whether the run ever parked on a human decision
+-- (`interrupted`). Sticky: set by the pause and never cleared by the resume, so
+-- `run.finished` can separate runs that waited for a person from runs that did
+-- not.
+--
+-- NOT NULL with a constant default: Postgres 11+ stores the default once in the
+-- catalog, so neither ADD COLUMN rewrites `runs`. Existing rows read 0 and false:
+-- nothing journaled their past closes, and nothing recorded their pauses.
+--
+-- No index and no CHECK. Nothing filters on either; both are written by the box
+-- store alone. No trigger change: `notify_run_event` (0001) keys on `started_at`
+-- and `finished_at` only.
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS event_seq integer NOT NULL DEFAULT 0;
+
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS waited_for_approval boolean NOT NULL DEFAULT false;

package/migrations/0078_run_steps_event_seq.sql

@@ -0,0 +1,31 @@
+-- 0078_run_steps_event_seq.sql — the two columns a run step needs to journal its
+-- end (PLA-1726, PRD PLA-1685).
+--
+-- A step's events (`workflow_step.finished`, `model_call.finished`,
+-- `connector_call.finished`, `tool_call.finished`) ride the upsert that writes
+-- the step's row, and the upsert itself decides whether the write is an end:
+--
+-- `event_status`: the final status (`completed`, `failed`, `cancelled`) the row's
+-- last event reported. NULL while the row is open: a write that re-arms the row
+-- (a World retry of a step whose tool calls are keyed by position) clears it, so
+-- the next end journals again. It is NOT `status`: the run's final sweep closes a
+-- row left `running` without journaling anything, and the real outcome that
+-- arrives later still has to journal.
+--
+-- `event_seq`: how many step events the row has journaled. The upsert adds 1 when
+-- the row reaches a final status that differs from `event_status`, and the event
+-- carries the new value, so the same end written twice journals once and each
+-- real end is its own event.
+--
+-- NOT NULL with a constant default: Postgres 11+ stores the default once in the
+-- catalog, so neither ADD COLUMN rewrites `run_steps`. Existing rows read 0 and
+-- NULL: nothing journaled their past ends.
+--
+-- No index and no CHECK. Nothing filters on either; both are written by the box
+-- store alone. No trigger change: `notify_run_step_event` (0018) keys on
+-- `completed_at` only.
+ALTER TABLE stackbone_platform.run_steps
+    ADD COLUMN IF NOT EXISTS event_seq integer NOT NULL DEFAULT 0;
+
+ALTER TABLE stackbone_platform.run_steps
+    ADD COLUMN IF NOT EXISTS event_status text;

package/migrations/0079_approvals_event_seq.sql

@@ -0,0 +1,32 @@
+-- 0079_approvals_event_seq.sql — the two columns an approval needs to journal its
+-- request and its end (PLA-1727, PRD PLA-1685).
+--
+-- The box approvals store is the one writer that journals approval events
+-- (`approval.created`, `approval.decided`, `approval.timed_out`), in the
+-- transaction of the write each one describes. The SDK's agent-local INSERT
+-- still writes this table directly and journals nothing.
+--
+-- `event_seq`: how many approval events the row has journaled. Each event adds 1
+-- and carries the new value, so a row re-armed by a key a new request reused
+-- keys its second request, decision or timeout apart from the first. 0 on a row
+-- the box store never journaled.
+--
+-- `requested_at`: when the box store journaled the request that is open now: set
+-- by the INSERT and by every re-arm. A re-arm clears `decided_at`, and
+-- `created_at` names the first request only, so the time to a decision counts
+-- from this column. NULL on a row whose request the box never saw (the SDK wrote
+-- it), and its end reports `request_observed = false`.
+--
+-- `event_seq` is NOT NULL with a constant default and `requested_at` is nullable
+-- with none: Postgres 11+ rewrites nothing for either ADD COLUMN, and every
+-- existing row reads 0 and NULL, since nothing journaled its request.
+--
+-- No index and no CHECK: nothing filters on either, and only the box store
+-- writes them. No trigger change: `notify_approval_event` (0002) keys on the
+-- INSERT, `decided_at` and `status` only, so the live `approval.created` still
+-- fires on the INSERT alone and a re-arm sends none.
+ALTER TABLE stackbone_platform.approvals
+    ADD COLUMN IF NOT EXISTS event_seq integer NOT NULL DEFAULT 0;
+
+ALTER TABLE stackbone_platform.approvals
+    ADD COLUMN IF NOT EXISTS requested_at timestamptz;

package/migrations/0080_run_steps_model_call_tokens_idx.sql

@@ -0,0 +1,15 @@
+-- 0080_run_steps_model_call_tokens_idx.sql — the index a run's token totals are
+-- read through (PLA-1715, PRD PLA-1685).
+--
+-- A run's tokens are the sums of its `model_call` rows, read at every Runs,
+-- run detail, Sessions and Evals query (`runs/run-token-totals.ts` in the box
+-- runtime), and `model_call.finished` journals the same rows. The only index on
+-- `run_id` so far is `(run_id, started_at)`, which finds a run's steps of every
+-- type and then fetches each row to read its type and counters.
+--
+-- Partial on `type = 'model_call'`, so it holds only the rows the fragment sums,
+-- and covering (`INCLUDE`) the four counters, so the sum is an index-only scan.
+CREATE INDEX IF NOT EXISTS run_steps_model_call_tokens_idx
+    ON stackbone_platform.run_steps (run_id)
+    INCLUDE (input_tokens, output_tokens, cache_read_tokens, cache_write_tokens)
+    WHERE type = 'model_call';

package/migrations/0081_runs_world_closed_at.sql

@@ -0,0 +1,27 @@
+-- 0081_runs_world_closed_at.sql — when the World run behind a cancelled row was
+-- confirmed ended (PLA-1716, PRD PLA-1685).
+--
+-- A cancel writes `runs.status = 'cancelled'` at once, but the World workflow
+-- behind the row keeps running: the SDK has no cancel signal yet. A `serial`
+-- workflow's lock belongs to that World run, so it may only be freed once the
+-- World run really ends, and the reconciliation sweep is the one place that
+-- looks. The sweep lists open rows only (`running`, `interrupted`), so it never
+-- revisited a cancelled row and the lock stayed held until the process restarted,
+-- with every queued trigger stuck `waiting` behind it.
+--
+-- `world_closed_at` is the sweep's bookmark for a cancelled row: NULL while the
+-- World run behind it may still be alive, so the sweep keeps listing the row; set
+-- once a pass saw that World run completed, failed, cancelled or gone, AFTER that
+-- pass freed the serial lock. The row's status never changes and nothing else
+-- reads it.
+--
+-- NULLABLE, NO DEFAULT, NO BACKFILL. A row cancelled before this migration reads
+-- NULL and is swept once more; the release is a no-op when this process does not
+-- hold its lock, and the pass then sets the column.
+--
+-- NO INDEX. The sweep query (`listOpenWorkflowRunTraceIds` in the box runtime)
+-- already reads `runs` without an index on `status`; adding the cancelled rows to
+-- its predicate does not change that plan, and a partial index on only that half
+-- of an OR would not be used for the whole predicate.
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS world_closed_at timestamptz;

package/migrations/0082_insights_widget.sql

@@ -0,0 +1,42 @@
+-- 0082_insights_widget.sql — the widgets saved on this box (PLA-1734, PRD
+-- PLA-1684). A widget is a saved query with its visualisation: a named,
+-- versioned document Studio's Widget Builder edits and a dashboard places.
+--
+-- Numbered against this feature branch, whose last migration is 0081; `next`
+-- and `main` stop at 0072. The runner keys `schema_migrations` on the four-digit
+-- prefix alone, so `scripts/check-migration-numbers.mjs` is the pre-merge gate:
+-- renumber against the tip you merge into.
+--
+-- Stored per box, like runs and approvals: every reader of one installation sees
+-- the same library in any browser, and two installations never share one. The
+-- control plane stores nothing about widgets.
+--
+-- `definition` is the whole widget document (display, query, presentation), as
+-- `@stackbone/insights-contract` validates it. Its shape version travels inside
+-- it (`definition.schemaVersion`), so there is no column for it and no upgrade on
+-- read: no older shape exists yet.
+--
+-- `revision` starts at 1 and every update bumps it. An update names the revision
+-- it was based on, and the box writes only when that is still the stored one:
+-- the second of two concurrent saves gets `revision_conflict`, never a silent
+-- overwrite.
+--
+-- `copied_from` names the widget this one was duplicated from. NO foreign key:
+-- the origin may be deleted, and the copy keeps saying where it came from.
+--
+-- `created_by` / `updated_by` are the acting user's id as the box reads it (a
+-- verified identity, or the control-plane proxy's actor header): free text and
+-- nullable, like `model_selections.updated_by` (0073). A `stackbone dev` write
+-- names nobody.
+CREATE TABLE IF NOT EXISTS stackbone_platform.insights_widget (
+    id           uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    name         text        NOT NULL,
+    description  text        NOT NULL DEFAULT '',
+    definition   jsonb       NOT NULL,
+    revision     integer     NOT NULL DEFAULT 1 CHECK (revision >= 1),
+    copied_from  uuid,
+    created_by   text,
+    updated_by   text,
+    created_at   timestamptz NOT NULL DEFAULT now(),
+    updated_at   timestamptz NOT NULL DEFAULT now()
+);

package/migrations/0083_insights_dashboard.sql

@@ -0,0 +1,64 @@
+-- 0083_insights_dashboard.sql — the dashboards saved on this box and the widget
+-- each of their placements references (PLA-1735, PRD PLA-1684). A dashboard is
+-- a saved composition of widgets placed in a slot: a named, versioned document
+-- Studio's Dashboard Builder edits.
+--
+-- Numbered against this feature branch, whose last migration is 0082; `next`
+-- and `main` stop at 0072. The runner keys `schema_migrations` on the four-digit
+-- prefix alone, so `scripts/check-migration-numbers.mjs` is the pre-merge gate:
+-- renumber against the tip you merge into.
+--
+-- `insights_dashboard` mirrors `insights_widget` (0082): `definition` is the
+-- whole composition (placements, filters, required filters) as
+-- `@stackbone/insights-contract` validates it, its shape version inside it;
+-- `revision` is the counter an update must name; `copied_from` carries no
+-- foreign key, so a copy keeps naming an origin that was deleted. `slot` is the
+-- place in Studio the dashboard lives in (`DASHBOARD_SLOTS`), and it never
+-- changes once the row exists. The list of one slot reads newest first through
+-- `insights_dashboard_slot_updated_idx`.
+--
+-- `insights_dashboard_widget` holds one row per placement: which widget it
+-- places. The layout stays in `definition`; these rows copy its widget ids and
+-- the box rewrites them in the SAME transaction as every save. They exist for
+-- integrity and for the usage lookup, not as a second copy of the layout:
+--
+--   - `insights_dashboard_widget_widget_fk` is `ON DELETE RESTRICT`, the first
+--     in this migration set. Deleting a widget a dashboard places fails with
+--     SQLSTATE 23503 under that name, and the box answers `widget_in_use`. The
+--     database decides, so a dashboard save racing the delete cannot slip a
+--     reference past a check the box made first.
+--   - `insights_dashboard_widget_dashboard_fk` is `ON DELETE CASCADE`: deleting
+--     a dashboard frees every widget it placed.
+--   - The key is the placement, so one widget can sit on a dashboard twice.
+--   - `insights_dashboard_widget_widget_idx` serves "which dashboards place this
+--     widget", and the RESTRICT check the delete runs.
+CREATE TABLE IF NOT EXISTS stackbone_platform.insights_dashboard (
+    id           uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    slot         text        NOT NULL,
+    name         text        NOT NULL,
+    description  text        NOT NULL DEFAULT '',
+    definition   jsonb       NOT NULL,
+    revision     integer     NOT NULL DEFAULT 1 CHECK (revision >= 1),
+    copied_from  uuid,
+    created_by   text,
+    updated_by   text,
+    created_at   timestamptz NOT NULL DEFAULT now(),
+    updated_at   timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS insights_dashboard_slot_updated_idx
+    ON stackbone_platform.insights_dashboard (slot, updated_at);
+
+CREATE TABLE IF NOT EXISTS stackbone_platform.insights_dashboard_widget (
+    dashboard_id  uuid NOT NULL,
+    placement_id  text NOT NULL,
+    widget_id     uuid NOT NULL,
+    PRIMARY KEY (dashboard_id, placement_id),
+    CONSTRAINT insights_dashboard_widget_dashboard_fk FOREIGN KEY (dashboard_id)
+        REFERENCES stackbone_platform.insights_dashboard (id) ON DELETE CASCADE,
+    CONSTRAINT insights_dashboard_widget_widget_fk FOREIGN KEY (widget_id)
+        REFERENCES stackbone_platform.insights_widget (id) ON DELETE RESTRICT
+);
+
+CREATE INDEX IF NOT EXISTS insights_dashboard_widget_widget_idx
+    ON stackbone_platform.insights_dashboard_widget (widget_id);

package/migrations/0084_insights_team_overview.sql

@@ -0,0 +1,33 @@
+-- 0084_insights_team_overview.sql — which saved dashboards each Studio team's
+-- Overview shows, in order (PLA-1736, PRD PLA-1684). The storage PLA-1683's
+-- Overview reads; the screen that edits it is not part of this migration.
+--
+-- Numbered against this feature branch, whose last migration is 0083; `next`
+-- and `main` stop at 0072. The runner keys `schema_migrations` on the four-digit
+-- prefix alone, so `scripts/check-migration-numbers.mjs` is the pre-merge gate:
+-- renumber against the tip you merge into.
+--
+-- One row per dashboard a team shows. `team` is a Studio team id
+-- (`STUDIO_TEAM_IDS` in `@stackbone/validators`); the box refuses any other, and
+-- the column carries no CHECK so a new team needs no migration. The box replaces
+-- a team's rows whole, in one transaction, so a reorder never leaves half a list.
+--
+--   - `PRIMARY KEY (team, dashboard_id)`: a team shows a dashboard once.
+--   - `insights_team_overview_position_key`: one dashboard per position of a
+--     team. Positions start at 0.
+--   - `insights_team_overview_dashboard_fk` is `ON DELETE CASCADE`: deleting a
+--     dashboard takes it off every team's Overview. On insert it is also how the
+--     box learns a listed dashboard does not exist (SQLSTATE 23503 under that
+--     name), which it answers as `unknown_dashboard`.
+--
+-- No index on `dashboard_id` alone: four teams' lists is a table the cascade
+-- reads whole faster than it would read an index.
+CREATE TABLE IF NOT EXISTS stackbone_platform.insights_team_overview (
+    team          text    NOT NULL,
+    dashboard_id  uuid    NOT NULL,
+    position      integer NOT NULL CHECK (position >= 0),
+    PRIMARY KEY (team, dashboard_id),
+    CONSTRAINT insights_team_overview_position_key UNIQUE (team, position),
+    CONSTRAINT insights_team_overview_dashboard_fk FOREIGN KEY (dashboard_id)
+        REFERENCES stackbone_platform.insights_dashboard (id) ON DELETE CASCADE
+);

package/migrations/0085_insights_widget_updated_idx.sql

@@ -0,0 +1,10 @@
+-- 0085_insights_widget_updated_idx.sql — the index the widget library is read
+-- through (PLA-1684).
+--
+-- `GET /api/insights/widgets` answers every saved widget, most recently updated
+-- first (`ORDER BY updated_at DESC, created_at DESC` in the box's Insights
+-- store), and 0082 created the table with its primary key only, so every read
+-- of the library sorted the whole table. The index carries that order, both
+-- columns, so the read walks it instead.
+CREATE INDEX IF NOT EXISTS insights_widget_updated_idx
+    ON stackbone_platform.insights_widget (updated_at DESC, created_at DESC);

package/migrations/0086_insights_now_metrics_idx.sql

@@ -0,0 +1,29 @@
+-- 0086_insights_now_metrics_idx.sql — the indexes the Insights "now" metrics
+-- are read through (PLA-1725, PRD PLA-1685).
+--
+-- Three metrics read the current state of a domain table instead of the event
+-- journal, on every query, never from a cache (the box runtime's
+-- `insights/engine/catalog/now-metrics.ts`):
+--
+--   - `approvals_pending`: approvals in `pending`, by `topic` and whether the
+--     sweep will time them out (`timeout_at` and `fallback`);
+--   - `runs_active`: runs `running` or `interrupted`, by status and workflow or
+--     agent (`entity_name`). `runs` had no index on `status` at all;
+--   - `outputs_waiting`: parked outputs not settled yet, by `workflow_name`,
+--     `kind` and `reason`.
+--
+-- Each index is partial on the metric's predicate, spelled as the metric spells
+-- it so the planner proves the index covers the read, and holds the columns its
+-- properties read, so a count by any of them is an index-only scan over the
+-- rows the metric counts and no others.
+CREATE INDEX IF NOT EXISTS approvals_pending_now_idx
+    ON stackbone_platform.approvals (topic, timeout_at, fallback)
+    WHERE status = 'pending';
+
+CREATE INDEX IF NOT EXISTS runs_active_now_idx
+    ON stackbone_platform.runs (entity_name, status)
+    WHERE status IN ('running', 'interrupted');
+
+CREATE INDEX IF NOT EXISTS parked_file_outputs_waiting_now_idx
+    ON stackbone_platform.parked_file_outputs (workflow_name, kind, reason)
+    WHERE settled_at IS NULL;

package/migrations/0087_auto_map_model_to_model_selection.sql

@@ -0,0 +1,28 @@
+-- 0087_auto_map_model_to_model_selection.sql — Auto-map's model moves from the
+-- `autoMapModel` workspace setting onto its catalog entry (PLA-1745).
+--
+-- The default `mapping-suggest` workflow now reads its model with
+-- `stackbone.models.use('model')`, so the pick lives where the entry's Models
+-- block edits it: the (workflow, mapping-suggest, model) row of
+-- `model_selections` (0073). A box that already saved `autoMapModel` keeps
+-- running that model: the value is COPIED once, here, rather than read as a
+-- fallback, because a fallback would keep a value in force that no screen shows.
+--
+-- A box that already holds a selection under that key keeps it: the operator
+-- picked it on the entry, which is the newer of the two editors. `ON CONFLICT DO
+-- NOTHING` is that rule.
+--
+-- The setting is then removed from the payload in every case, copied or not, so
+-- nothing is left for a stale reader to find. An empty string or a JSON null
+-- names no model and copies nothing.
+INSERT INTO stackbone_platform.model_selections (owner_kind, owner_name, key, model_id)
+SELECT 'workflow', 'mapping-suggest', 'model', payload ->> 'autoMapModel'
+  FROM stackbone_platform.workspace_settings
+ WHERE id = 1
+   AND coalesce(payload ->> 'autoMapModel', '') <> ''
+ON CONFLICT (owner_kind, owner_name, key) DO NOTHING;
+
+UPDATE stackbone_platform.workspace_settings
+   SET payload = payload - 'autoMapModel'
+ WHERE id = 1
+   AND payload ? 'autoMapModel';

package/migrations/0088_recurring_job_pauses.sql

@@ -0,0 +1,27 @@
+-- 0088_recurring_job_pauses.sql — the recurring jobs an operator paused from
+-- Studio (PLA-1842).
+--
+-- A PAUSE is one row per pause key. The key names a GROUP of recurring jobs that
+-- stop and start together: a workflow pauses as `workflow:<name>`, which covers
+-- every cron it declares (`decl:<name>#<n>`) and the one it registers at run time
+-- (`dyn:<name>`). Keying on the scheduler id instead would not survive a
+-- redeploy: a declared id is the cron's POSITION in `schedules`, so reordering
+-- the list would move the pause onto another cron.
+--
+-- The box reads every row at boot and arms nothing a row names, so a pause holds
+-- across restarts and redeploys. Resuming deletes the row: "no row" means "not
+-- paused", and the activity log (`recurring_job.pause` / `recurring_job.resume`)
+-- is the history this table does not keep.
+--
+-- No CHECK on the key's shape, for the reason 0073 gives for `owner_kind`: a box
+-- running an older build must still be able to STORE a key it cannot resolve. A
+-- key no declared job carries pauses nothing, which is the safe failure.
+--
+-- `paused_by` is the acting user's id as the box reads it, free text and
+-- nullable like `model_selections.updated_by` (0073). A `stackbone dev` write
+-- names nobody.
+CREATE TABLE IF NOT EXISTS stackbone_platform.recurring_job_pauses (
+    pause_key  text        PRIMARY KEY,
+    paused_by  text,
+    paused_at  timestamptz NOT NULL DEFAULT now()
+);