@stackbone/cli 0.3.3 → 0.3.5

package/migrations/0047_prompts_owner.sql

@@ -0,0 +1,99 @@
+-- 0047_prompts_owner.sql — a prompt belongs to ONE workflow or ONE deep agent,
+-- not to the whole installation (STA-398).
+--
+-- 0013 made `key` a workspace-wide PRIMARY KEY. That reads fine with three
+-- prompts and breaks the moment two entries want the same obvious name: the
+-- sign-up workflow's `welcome_email` and the reactivation workflow's
+-- `welcome_email` are different letters, and under the old key the second one
+-- could not be written at all — `prompts_already_exists`, with the operator's
+-- only way out being to invent `welcome_email_2`. Identity becomes the PAIR
+-- (owner, key), where the owner is `(owner_kind, owner_name)`.
+--
+-- The vocabulary is the one the box already uses for the same idea. A guardrail
+-- attachment (0036) is scoped to an `agent` or a `workflow` unit by NAME, and a
+-- run (0037) records its `entity_kind` for the same reason: a deep agent and a
+-- workflow may legitimately share a name, so the kind is part of the identity.
+-- Prompts drop 0036's third value — there is no workspace-wide prompt, because
+-- a prompt with no owner is exactly the thing this migration exists to remove.
+--
+-- Deliberately NO CHECK constraint on `owner_kind`, following 0036 and 0037: a
+-- box running an older build must be able to STORE a kind it cannot resolve
+-- rather than reject the write and lose the operator's text. An unrecognised
+-- kind simply never matches a read, which is the safe failure.
+--
+-- `owner_name` is an unconstrained free string like 0036's `unit_id`, NOT the
+-- lowercase slug `key` is validated against on the wire: a workflow named
+-- `sendWelcomeEmail` is a legitimate name the guardrails surface already
+-- accepts for the identical concept, and a stricter column here would refuse to
+-- store a prompt for a workflow that exists.
+--
+-- DROP + CREATE rather than a widening ALTER, on purpose. There is no deployed
+-- installation to preserve, and the alternative — adding two NOT NULL columns to
+-- rows that carry no owner — would need an invented default owner for the
+-- backfill, which is a guess about whose prompt each row was. Rebuilding the two
+-- tables keeps the schema honest instead of encoding that guess.
+
+DROP TABLE IF EXISTS stackbone_platform.prompt_versions;
+DROP TABLE IF EXISTS stackbone_platform.prompts;
+
+CREATE TABLE stackbone_platform.prompts (
+    -- The owner's kind: `agent` (a deep agent) or `workflow`. See above for why
+    -- there is no CHECK and no `workspace` member.
+    owner_kind        text        NOT NULL,
+    -- The owner's NAME, as the bundle declares it.
+    owner_name        text        NOT NULL,
+    key               text        NOT NULL,
+    name              text        NOT NULL,
+    description       text,
+    -- The version number considered live. Always points at an existing row in
+    -- `prompt_versions` for this (owner, key).
+    current_version   integer     NOT NULL CHECK (current_version >= 1),
+    metadata          jsonb,
+    created_by_email  text,
+    updated_by_email  text,
+    created_at        timestamptz NOT NULL DEFAULT now(),
+    updated_at        timestamptz NOT NULL DEFAULT now(),
+    -- Soft delete. Active prompts have `deleted_at IS NULL`; reads filter on it
+    -- so the rows survive for the retention window.
+    deleted_at        timestamptz,
+    PRIMARY KEY (owner_kind, owner_name, key)
+);
+
+CREATE TABLE stackbone_platform.prompt_versions (
+    id                uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    -- All three identity columns, not a widened `prompt_key`: the parent's key
+    -- is composite now, so a composite FK needs the child to carry every part of
+    -- it. Without them a version row could not say which owner's chain it is in.
+    owner_kind        text        NOT NULL,
+    owner_name        text        NOT NULL,
+    prompt_key        text        NOT NULL,
+    version           integer     NOT NULL CHECK (version >= 1),
+    content           text        NOT NULL,
+    -- Pre-computed list of the `{{vars}}` referenced by `content`, so Studio's
+    -- diff view can highlight added/removed variables without re-parsing.
+    vars_extracted    jsonb       NOT NULL DEFAULT '[]'::jsonb,
+    -- Source version when this row was created by a rollback/promote; NULL for
+    -- a regular edit.
+    rolled_back_from  integer,
+    created_by_email  text,
+    created_at        timestamptz NOT NULL DEFAULT now(),
+    FOREIGN KEY (owner_kind, owner_name, prompt_key)
+        REFERENCES stackbone_platform.prompts (owner_kind, owner_name, key)
+        ON DELETE CASCADE
+);
+
+-- One version number per (owner, key) — the race backstop behind the
+-- `MAX(version) + 1` the application assigns under a per-prompt advisory lock.
+-- The lock key folds the owner in for the same reason this index leads with it.
+CREATE UNIQUE INDEX IF NOT EXISTS prompt_versions_owner_key_version_idx
+    ON stackbone_platform.prompt_versions (owner_kind, owner_name, prompt_key, version);
+
+-- Drives the history list (newest first) for one owner's key.
+CREATE INDEX IF NOT EXISTS prompt_versions_owner_key_version_desc_idx
+    ON stackbone_platform.prompt_versions (owner_kind, owner_name, prompt_key, version DESC);
+
+-- The list endpoint orders active prompts by owner, then key, so a screen shows
+-- each owner's prompts together.
+CREATE INDEX IF NOT EXISTS prompts_active_owner_key_idx
+    ON stackbone_platform.prompts (owner_kind, owner_name, key)
+    WHERE deleted_at IS NULL;

package/migrations/0048_prompt_publish.sql

@@ -0,0 +1,58 @@
+-- 0048_prompt_publish.sql — writing a prompt and publishing it are two steps
+-- (STA-400).
+--
+-- Until now the version that ran was always the highest one that existed: the
+-- head's pointer only ever moved forward (`GREATEST(current_version, $n)`), so
+-- saving an edit put it straight in front of the agent, and going back to an
+-- earlier wording had to COPY that wording into a brand-new version number. An
+-- operator debugging a run then saw `v7` in the logs and `v3`'s text in the
+-- prompt, with nothing on screen tying the two together.
+--
+-- The head now carries two numbers instead of one:
+--
+--   * `latest_version`    — the newest version anyone has WRITTEN. This is the
+--                           old `current_version`, renamed to say what it always
+--                           actually held.
+--   * `published_version` — the one that RUNS. Nullable, because "nothing is
+--                           published" is a real state: a prompt whose pointer
+--                           has been cleared reads as having no content, which
+--                           is what makes deleting it (and its versions)
+--                           possible at all.
+--
+-- Publishing moves `published_version` onto a version that already exists. It
+-- never inserts, so the number an operator picked is the number the logs show.
+-- The history stays append-only for EDITS — every save is still an immutable new
+-- row under the unique `(owner, key, version)` index from 0047.
+--
+-- `rolled_back_from` goes with the copy it recorded. It existed to stamp "this
+-- row was born from v3" on the duplicate a rollback inserted; publishing inserts
+-- nothing, so there is no row left to stamp and the column would be NULL on
+-- every future version. Dropped rather than left as a field that can only ever
+-- answer "no".
+--
+-- Both numbers are deliberately left WITHOUT a foreign key onto
+-- `prompt_versions`. A composite FK would force the create path to insert the
+-- head, then the version, then update the head — three statements where two do,
+-- for an invariant the routes already enforce (a publish validates its target
+-- first, and the published version cannot be deleted).
+
+ALTER TABLE stackbone_platform.prompts
+    RENAME COLUMN current_version TO latest_version;
+
+-- Nullable now: deleting a prompt's last draft leaves a head with no versions at
+-- all, which reads as no content rather than as a broken row.
+ALTER TABLE stackbone_platform.prompts
+    ALTER COLUMN latest_version DROP NOT NULL;
+
+ALTER TABLE stackbone_platform.prompts
+    ADD COLUMN IF NOT EXISTS published_version integer CHECK (published_version >= 1);
+
+-- Everything written before this migration ran under "the newest version is the
+-- live one", so that is exactly what was published. Without the backfill every
+-- existing prompt would go dark on deploy.
+UPDATE stackbone_platform.prompts
+   SET published_version = latest_version
+ WHERE published_version IS NULL;
+
+ALTER TABLE stackbone_platform.prompt_versions
+    DROP COLUMN IF EXISTS rolled_back_from;

package/migrations/0049_run_steps_annotations.sql

@@ -0,0 +1,46 @@
+-- 0049_run_steps_annotations.sql — give a `run_steps` row somewhere to carry what
+-- the SYSTEM observed about the step, next to (never inside) what the creator's
+-- code passed through it. First tenant: which prompt, whose, and at what version
+-- governed the step (STA-404).
+--
+-- WHY A NEW COLUMN AT ALL. `run_steps` has exactly three JSON columns — `input`,
+-- `output` and `error` — and all three hold the CREATOR's payload: the arguments
+-- a tool was called with, what it answered, how it broke. Folding an annotation
+-- into any of them would mix two things that are read for different reasons and
+-- have different lifetimes, and would show up in the trace viewer's Inspector as
+-- if the creator had returned it. The only other free slot in the schema is
+-- `runs.metadata`, which hangs off the RUN and not the step (and is already taken
+-- by the eval seal), so it cannot answer "what ran in THIS step".
+--
+-- WHY `annotations` AND NOT `prompt_uses`. The next per-step annotation — a
+-- guardrail's verdict fold, a retry note, whatever it turns out to be — should
+-- not need a fourth ALTER on this table. So the column is one jsonb OBJECT whose
+-- top-level keys name the annotation kinds, and this feature owns exactly one of
+-- them:
+--
+--   {"prompts": [{"ownerKind": "workflow", "ownerName": "qualify-lead",
+--                 "key": "welcome", "version": 3, "reason": null}]}
+--
+-- `reason` is null on a healthy read and names the degradation otherwise
+-- (`not_found` / `not_published` / `deleted` / `missing_var` / `no_owner` /
+-- `unavailable`); `version` is null exactly when `reason` is not. The wire shape
+-- is `runStepPromptUseSchema` in `@stackbone/validators`, the one schema the box,
+-- the emulator and Studio all read.
+--
+-- NULLABLE, no default, no backfill. Every row already written keeps reading back
+-- with the column NULL, and the read path maps NULL to "this step read no
+-- prompts" — so a run that used none looks exactly as it did before this
+-- migration. There is nothing deployed to migrate, but a `DEFAULT '{}'` would
+-- still have rewritten every existing row for no gain.
+--
+-- No index: this is read only alongside the row it annotates (the step listing
+-- already selects by `run_id`), never searched across runs.
+--
+-- The pg_notify trigger (`notify_run_step_event`) streams the row's identity and
+-- status, not its columns, so no trigger change is needed.
+
+ALTER TABLE stackbone_platform.run_steps
+    ADD COLUMN IF NOT EXISTS annotations jsonb;
+
+COMMENT ON COLUMN stackbone_platform.run_steps.annotations IS
+    'System observations about this step, keyed by annotation kind. `prompts` holds the prompt reads (STA-404). Never the creator payload — that is input/output/error.';

package/migrations/0050_run_steps_model_provider.sql

@@ -0,0 +1,30 @@
+-- 0050_run_steps_model_provider.sql — give the model its own home on a run step.
+--
+-- Until now the model id had nowhere to live, so it shared the `name` column with
+-- whatever else each writer put there: a direct `client.ai` call stores the model
+-- id, a deep-agent invocation stores the AGENT's name. Both read back as "name",
+-- and nothing on the row says which of the two it is — so the trace viewer could
+-- only print `name` and hope.
+--
+-- Two nullable text columns fix that. `name` keeps meaning whatever each writer
+-- already means by it; it simply stops being where a reader looks for the model.
+--
+-- `provider` is DERIVED from the model id's prefix, never guessed. The ids the box
+-- speaks are OpenRouter-style `vendor/model`, so `openai/gpt-4o-mini` yields
+-- `openai`, and an id with no prefix leaves the column NULL rather than inventing
+-- one. `openrouter` is never stored: it is the gateway that routed the call, not
+-- the provider that served it.
+--
+-- Both columns are nullable with no default and no CHECK, because every row
+-- written before this migration has neither and must stay readable: the trace
+-- viewer falls back to `name` when `model` is null.
+--
+-- Viewer posture is UNCHANGED. 0005 grants SELECT on the TABLE
+-- (`GRANT SELECT ON ALL TABLES IN SCHEMA stackbone_platform`), which covers every
+-- column the table ever grows, and no column-level revoke exists to undo it. So a
+-- new column needs no grant of its own — the DB Explorer sees these two the moment
+-- they exist.
+
+ALTER TABLE stackbone_platform.run_steps
+    ADD COLUMN IF NOT EXISTS model    text,
+    ADD COLUMN IF NOT EXISTS provider text;

package/migrations/0051_logs.sql

@@ -0,0 +1,137 @@
+-- 0051_logs.sql — the box's OWN log table (PLA-741, parent PLA-231).
+--
+-- Numbered 0051 against `main`, whose last migration is 0050. The runner keys
+-- `schema_migrations` on the four-digit prefix alone, so two branches that both
+-- take the next free number do not merely collide untidily: the loser applies its
+-- DDL and then dies on the journal's primary key, and the retry reports a
+-- checksum mismatch that points the operator at the wrong problem.
+-- `scripts/check-migration-numbers.mjs` (PLA-735) is the pre-merge gate for that;
+-- renumber against the tip you are merging into, not the one you branched from.
+-- The 0046 → 0050 gap is legal — the migrator applies a late lower number on its
+-- next run, which is why the unmerged 0047-0049 of another branch are harmless.
+--
+-- ONE PLAIN TABLE, not a partitioned one. Retention here is a DELETE by age, and
+-- a box's log volume is bounded by the pipe's own four brakes (a per-line size
+-- cap, a per-run line cap, a per-box daily cap — `log-pipe.ts`). Partitioning
+-- buys a `DROP PARTITION` instead of a batched `DELETE`, at the price of a
+-- partition maintenance job that has to run BEFORE the writes it serves; a box
+-- whose maintenance job missed a tick would start rejecting log lines, which is
+-- exactly the failure mode this feature exists to avoid. Every read and write
+-- goes through the log-domain port (`logs-store.ts`), so moving to partitions
+-- later is a change behind that seam with no data migration and no caller edit.
+--
+-- NO WORKSPACE COLUMN. The box has no honest source for one: it is a single
+-- installation, and the only tenant identifier it ever sees arrives per request
+-- on a JWT claim, not on the boot line it is writing at the time. One box is one
+-- installation, so the scope of every row is the database it lives in. A column
+-- filled with a constant would invite a reader to filter on it.
+--
+--   ts            — when the line was written, from the pipe's clock. The
+--                   retention sweep and every read order by it.
+--   level         — Pino's NUMERIC level (10 trace … 60 fatal), matching the
+--                   record the pipe builds and the tail's `>=` filter. A text
+--                   level would make "warn and above" a CASE expression.
+--   stream        — which of the process's two streams the line was written to.
+--   message       — the line itself, already scrubbed and already capped by the
+--                   pipe. The DDL imposes no length: the cap is a policy the box
+--                   owns, and a column limit would reject rather than truncate.
+--   run_id        — the run the line belongs to. NULL for a boot line, a
+--                   lifecycle line, a recurring job's line.
+--
+--                   DELIBERATELY NOT A FOREIGN KEY to `runs`, unlike `run_steps`.
+--                   Two ordinary sequences break under one: the first lines of a
+--                   run are written before its `runs` row is inserted, and a chat
+--                   turn whose start FAILED goes on logging with no run row that
+--                   will ever exist. An FK turns both into a rejected INSERT —
+--                   losing exactly the lines an operator opens the screen to
+--                   read. It would also chain this table into the runs table's
+--                   own retention, which is a separate policy.
+--   step_id       — the ENGINE's external step id, not a projected
+--                   `run_steps.id` uuid. Free text, minted outside Postgres.
+--   invocation_id — the World run id of a workflow invocation (the `trace_id` the
+--                   pipe stamps). Also free text and also not a key.
+--   fields        — the producer's own structured fields, minus the canonical
+--                   ones this table has columns for. JSONB rather than JSON so a
+--                   later slice can index a hot key without a rewrite.
+--   truncated     — the pipe hit its per-line cap and stored the head. A flag
+--                   rather than a silent short message: a reader has to be able
+--                   to tell a short line from a cut one.
+--   masked_count  — how many spans the scrubber removed. A COUNT, never the
+--                   values: it lets a reader tell "nothing here was secret" from
+--                   "three things were taken out of this".
+--   subject_id    — RESERVED for the compliance slice (PLA-718), which needs a
+--                   data-subject handle to answer an erasure request. Written by
+--                   nobody today. It ships now because adding a column to a table
+--                   holding a month of log rows is a rewrite of the whole heap,
+--                   and this is the cheapest moment it will ever be.
+CREATE TABLE IF NOT EXISTS stackbone_platform.logs (
+    id            uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    ts            timestamptz NOT NULL DEFAULT now(),
+    level         integer     NOT NULL,
+    stream        text        NOT NULL DEFAULT 'stdout',
+    message       text        NOT NULL,
+    run_id        uuid,
+    step_id       text,
+    invocation_id text,
+    fields        jsonb       NOT NULL DEFAULT '{}'::jsonb,
+    truncated     boolean     NOT NULL DEFAULT false,
+    masked_count  integer     NOT NULL DEFAULT 0,
+    subject_id    text
+);
+
+-- TWO indexes, and the argument for stopping there is as load-bearing as the
+-- argument for these two. Every index is paid for on EVERY insert, and this is
+-- the highest-insert table the box has.
+--
+--   (run_id, ts) — the run-scoped read: "this run's lines, oldest first".
+--   (ts)         — the retention sweep's own scan, and the global tail's paging.
+--
+-- NOT indexed, on purpose:
+--   level     — six distinct values over millions of rows. The planner would
+--               ignore it for anything but `fatal`, and a scan is cheaper.
+--   message   — no trigram index. Substring search is a BOUNDED scan (the reader
+--               always carries a time window), and a GIN trigram index over a
+--               month of log text costs a large fraction of the table it
+--               indexes — on the customer's own disk, for a search nobody runs
+--               on a cold box. The search slice that needs it can add it.
+--   ts (BRIN) — a BRIN index wins on an append-only table whose physical order
+--               matches its timestamps. This table is bulk-DELETEd hourly and
+--               its freed space is reused out of order, so the correlation the
+--               BRIN depends on decays exactly as the table ages.
+CREATE INDEX IF NOT EXISTS logs_run_id_ts_idx ON stackbone_platform.logs (run_id, ts);
+CREATE INDEX IF NOT EXISTS logs_ts_idx ON stackbone_platform.logs (ts);
+
+-- PER-TABLE AUTOVACUUM. The cluster default waits for dead tuples to reach 20% of
+-- the table before it even considers a vacuum. This is the one table the box
+-- bulk-deletes on a schedule, so on the defaults an hourly retention pass would
+-- leave its dead rows in place for hours, the heap would keep growing past what
+-- the operator's budget setting measures, and the visibility map would go stale
+-- under the very index the retention scan uses.
+--
+-- 1% plus a floor of 5 000 rows: the fraction keeps a big table vacuumed
+-- promptly, and the explicit threshold stops a nearly-empty table from vacuuming
+-- itself on every few writes.
+ALTER TABLE stackbone_platform.logs SET (
+    autovacuum_vacuum_scale_factor = 0.01,
+    autovacuum_vacuum_threshold = 5000
+);
+
+-- The read-only DB-Explorer role may not read log lines. Same reasoning as
+-- 0011_secrets_revoke_viewer.sql, and the same mechanism: 0005's blanket
+-- `ALTER DEFAULT PRIVILEGES … GRANT SELECT` already fires for every table created
+-- after it, so a table-level REVOKE is the only thing that strips the grant this
+-- CREATE just received.
+--
+-- Logs are the widest surface a credential can escape through. They are scrubbed
+-- on the way in (`log-scrubber.ts`) with both credential SHAPES and the box's own
+-- secret VALUES, but scrubbing is a best effort over free text and this is not:
+-- a `viewer` seat is read-only precisely because it is handed out widely.
+REVOKE ALL ON stackbone_platform.logs FROM stackbone_viewer;
+
+-- NO TRIGGERS. Every other table in this schema that Studio watches carries a row
+-- trigger emitting `pg_notify` on the platform channel. Not this one: the box
+-- logs its own boot, its own recurring jobs and every line of every run through
+-- the same pipe, so a per-row NOTIFY here would flood a channel the bridge shares
+-- with the run/step/session frames it exists to deliver — and a NOTIFY payload is
+-- capped at 8 000 bytes, which a log line can exceed on its own. The live tail is
+-- fed from the pipe IN MEMORY, before the row is ever written.

package/migrations/0052_telemetry_export_state.sql

@@ -0,0 +1,43 @@
+-- 0052_telemetry_export_state.sql — what the OTLP export has LOST (PLA-744).
+--
+-- Numbered 0052 against `main`, whose last migration is 0051. The runner keys
+-- `schema_migrations` on the four-digit prefix alone, so two branches that both
+-- take the next free number half-apply and then report a checksum mismatch that
+-- points at the wrong problem. `scripts/check-migration-numbers.mjs` is the
+-- pre-merge gate; renumber against the tip you merge into, not the one you
+-- branched from.
+--
+-- WHY A TABLE AND NOT A COUNTER IN MEMORY. The export is fail-open: a collector
+-- that refuses the connection costs the box its telemetry and nothing else, and
+-- the run goes on. That is the right trade and it is also how an integration
+-- goes quietly dead — a box that has exported nothing since a certificate
+-- expired looks exactly like a box nobody sends much traffic to. The count is
+-- the only thing that tells them apart, and it is worth nothing if it resets
+-- every time the container restarts, which is precisely when an operator looks.
+--
+-- ONE ROW, like `runtime_identity` (0033) and `runtime_control_plane_identity`
+-- (0046): this describes THE runtime's export, not a collection of anything.
+-- The writer upserts it, so the row's absence simply means nothing has been lost
+-- yet, and the read defaults to zero.
+--
+--   failure_count   — records that never reached the collector, over this box's
+--                     life: a batch a 4xx refused, a batch whose connection was
+--                     refused, the records a `partialSuccess` rejected, and the
+--                     oldest records the bounded queue dropped. RECORDS, not
+--                     batches — "we lost 40 000 lines" and "we lost 80 sends"
+--                     are different sentences and only the first is actionable.
+--                     `bigint` because a box exporting into a black hole for a
+--                     week passes 2^31.
+--   last_failure_at — when the counter last moved. A large count that stopped
+--                     moving yesterday is a fixed outage; the same count still
+--                     moving is an open one.
+--
+-- NO ENDPOINT COLUMN. Where the box exports to is deployment configuration read
+-- from `OTEL_EXPORTER_OTLP_ENDPOINT`, never a stored setting: a row Studio could
+-- write would let a seat redirect the operator's telemetry. The settings screen
+-- reads the endpoint's presence from the environment and the count from here.
+CREATE TABLE IF NOT EXISTS stackbone_platform.telemetry_export_state (
+    id              int         PRIMARY KEY DEFAULT 1 CHECK (id = 1),
+    failure_count   bigint      NOT NULL DEFAULT 0,
+    last_failure_at timestamptz
+);

package/migrations/0053_runs_exported_at.sql

@@ -0,0 +1,51 @@
+-- 0053_runs_exported_at.sql — HOW FAR the OTLP trace export has got on each run
+-- (PLA-746).
+--
+-- Numbered 0053 against `main`, whose last migration is 0050; this branch adds
+-- 0051 and 0052 ahead of it. The runner keys `schema_migrations` on the
+-- four-digit prefix alone, so two branches that both take the next free number
+-- half-apply and then report a checksum mismatch pointing at the wrong problem.
+-- `scripts/check-migration-numbers.mjs` is the pre-merge gate; renumber against
+-- the tip you merge into, not the one you branched from.
+--
+-- WHY A COLUMN AND NOT A QUEUE. `run.finished` (0001's row trigger) travels over
+-- LISTEN/NOTIFY, which reaches a connected listener and nobody else. A deploy
+-- that recycles the container loses the trace of every run closing around the
+-- restart, and a box that dies mid-turn loses it forever. This column is the one
+-- durable fact the sweep needs: the unexported rows ARE the retry queue, so a
+-- second queue would only be a second thing to lose.
+--
+-- A COMPARABLE WATERMARK, NOT A FLAG. `exported_at` holds the `finished_at`
+-- whose trace actually left the box, so the sweep asks
+--
+--     finished_at IS NOT NULL AND (exported_at IS NULL OR finished_at > exported_at)
+--
+-- and not "exported_at IS NULL". A run CAN close twice: the chat reconciler marks
+-- a dead `running` turn `failed`, and the live turn it raced then lands its own
+-- `complete()` — an UPDATE with no status guard, over a row whose `finished_at`
+-- is already set, which fires NO second `run.finished` (the trigger only notifies
+-- on the NULL → NOT NULL transition). Under a nullity check the operator's APM
+-- would say `failed` forever while Studio says done. Equality is the "already
+-- shipped" case and must NOT re-export, which is why the writer stamps the
+-- observed `finished_at` rather than `now()`: a value taken from the clock could
+-- land ahead of a close that happened while the trace was in flight, and that
+-- close would then never be exported at all.
+--
+-- NULLABLE, NO DEFAULT, NO BACKFILL. A NULL means "never exported", and on the
+-- first boot with OTLP enabled that is every run the box has ever recorded. The
+-- sweep does NOT send them: it cuts by the operator's log-retention window, so
+-- turning the export on is not an accidental replay of the box's whole history.
+-- A historical backfill is an explicit operator action, never a side effect.
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS exported_at timestamptz;
+
+-- The sweep's only query, as an index. PARTIAL on the same predicate the sweep
+-- uses, so a box whose export is keeping up scans an index holding almost
+-- nothing — the steady state is "every finished run is exported", and an index
+-- over the whole table would grow with the journal forever. The predicate names
+-- only columns (no `now()`), which is what makes it legal in an index at all;
+-- the age cutoffs are applied on top of it, at read time.
+CREATE INDEX IF NOT EXISTS runs_export_pending_idx
+    ON stackbone_platform.runs (finished_at)
+    WHERE finished_at IS NOT NULL
+      AND (exported_at IS NULL OR finished_at > exported_at);

package/migrations/0054_runs_trace_parent.sql

@@ -0,0 +1,35 @@
+-- 0054_runs_trace_parent.sql — the INBOUND trace a run continues (PLA-747).
+--
+-- Numbered 0054 against `main`, whose last migration is 0050; this branch adds
+-- 0051, 0052 and 0053 ahead of it. The runner keys `schema_migrations` on the
+-- four-digit prefix alone, so two branches that both take the next free number
+-- half-apply and then report a checksum mismatch pointing at the wrong problem.
+-- `scripts/check-migration-numbers.mjs` (PLA-735) is the pre-merge gate;
+-- renumber against the tip you merge into, not the one you branched from.
+--
+-- NOT `trace_id`. The column beside this one holds the WORLD runId — the box's
+-- own join key between a projected `runs` row and the workflow engine's run.
+-- `trace_parent` is the opposite direction: the W3C `traceparent` header a
+-- CALLER sent, naming a trace that was opened outside this box entirely. A
+-- reader who conflates the two searches the wrong id in the wrong system, so the
+-- names are deliberately not variations of each other.
+--
+-- HONOURED MEANS STORED. The header arrives on one HTTP request — `POST
+-- /api/workflows/:name/start`, the only door that can carry it today (the
+-- connector intake is polling and there is no inbound webhook receiver) — and
+-- the spans that need it leave minutes later, from a sweep with no request in
+-- scope. Memory would lose it on the next deploy; the row is the only place it
+-- survives to the export.
+--
+-- NULLABLE, NO DEFAULT, NO BACKFILL, NO CHECK. A NULL means "nobody sent one",
+-- which is what almost every run is. No CHECK for the same reason 0037 has none:
+-- the grammar is validated in the box before the write, and an older box must be
+-- able to STORE a value a newer build validated by a rule this one does not know.
+-- The read side re-parses it anyway (`otlp/traceparent.ts`), so a value that
+-- somehow got in malformed is ignored at export rather than breaking it.
+--
+-- NO INDEX. Nothing searches by it: every read is by the run's own primary key —
+-- the trace exporter reads the run it is exporting, the log exporter reads the
+-- run a log line names. An index would be a write cost with no reader.
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS trace_parent text;

package/migrations/0055_audit_log.sql

@@ -0,0 +1,105 @@
+-- 0055_audit_log.sql — the BOX's half of the organization activity log
+-- (PLA-898). One row per human mutation the box itself carried out: an approval
+-- decided, the creator's config saved or rolled back, a workspace setting
+-- changed.
+--
+-- Numbered 0055 against `next`, whose last migration is 0054. The runner keys
+-- `schema_migrations` on the four-digit prefix alone, so two branches that both
+-- take the next free number half-apply and then report a checksum mismatch
+-- pointing at the wrong problem. `scripts/check-migration-numbers.mjs` is the
+-- pre-merge gate; renumber against the tip you merge into.
+--
+-- THE SHAPE IS NOT THIS FILE'S TO CHOOSE. Nine of the ten columns below are the
+-- shared ones `auditColumns()` (`@stackbone/audit-core`) builds, the same set the
+-- control plane's `public.audit_log` is grown from, so the federated reader that
+-- merges the two timelines never has to translate between dialects.
+-- `libs/shared/box-schema/src/lib/schema/audit-log.spec.ts` is what holds the
+-- Drizzle definition, this DDL and that builder to one shape.
+--
+-- What only the box adds is `agent_id`: everything a box records happened while
+-- it was serving one agent, and the merged timeline's per-agent filter is matched
+-- on it. The control plane's table has no such column — nothing it records
+-- belongs to an agent at all.
+--
+-- NO FOREIGN KEYS. `organization_id` and `actor_user_id` are the control plane's
+-- ids, and neither an `organization` nor a `user` table exists inside a box, so
+-- there is nothing here for them to reference. `actor_user_id` is NULLABLE, and
+-- that is the point rather than a concession: a `stackbone dev` save happens with
+-- nobody signed in, and the honest row for it names no actor instead of failing
+-- the save or borrowing somebody's name. `organization_id` stays NOT NULL — a box
+-- nobody has registered records the nil uuid, which says "this box answers for no
+-- organization yet" and never claims a tenant it does not have.
+CREATE TABLE IF NOT EXISTS stackbone_platform.audit_log (
+    id              uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    organization_id uuid        NOT NULL,
+    actor_user_id   uuid,
+    agent_id        text,
+    action          text        NOT NULL,
+    subject_type    text        NOT NULL,
+    subject_id      uuid,
+    payload         jsonb       NOT NULL DEFAULT '{}'::jsonb,
+    metadata        jsonb       NOT NULL DEFAULT '{}'::jsonb,
+    created_at      timestamptz NOT NULL DEFAULT now()
+);
+
+-- The four indexes, three of them declared by `auditIndexes()` so both planes
+-- carry the same set under the same names. A name is unique per SCHEMA in
+-- Postgres — the control plane's table is in `public` and this one in
+-- `stackbone_platform` — so the repeated names read as "the same index" rather
+-- than collide. Twenty-four months of human actions is a small table, but the
+-- filters the contract promises should not start life as sequential scans.
+CREATE INDEX IF NOT EXISTS audit_log_organization_idx
+    ON stackbone_platform.audit_log (organization_id, created_at);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS audit_log_subject_idx
+    ON stackbone_platform.audit_log (subject_type, subject_id);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS audit_log_actor_idx
+    ON stackbone_platform.audit_log (organization_id, actor_user_id, created_at);
+--> statement-breakpoint
+-- The box's own: "everything this agent did", newest first.
+CREATE INDEX IF NOT EXISTS audit_log_agent_idx
+    ON stackbone_platform.audit_log (agent_id, created_at);
+--> statement-breakpoint
+
+-- THE TRAIL IS APPEND-ONLY, AND THE DATABASE IS WHAT SAYS SO.
+--
+-- The table has exactly one writer (the box audit recorder, inside the
+-- transaction the mutation it describes already holds) and no updater or deleter
+-- at all. That is a property of today's code, not a guarantee: any future
+-- handler, migration or psql session inside the customer's own infrastructure
+-- could rewrite history, and a trail that can be edited by whoever is being
+-- audited is not evidence. So the rule lives here, below every application, where
+-- no code path can forget it.
+--
+-- UNCONDITIONAL, unlike the control plane's twin (`db-core`'s 0023), which has to
+-- let one DELETE through: there, `audit_log.organization_id` is ON DELETE CASCADE
+-- and erasing an organization would otherwise be refused by its own children.
+-- Nothing here carries a foreign key, so there is no cascade to admit and no
+-- carve-out to write. Adding one "for parity" would open the only hole this
+-- trigger exists to close.
+--
+-- No retention exception. The age-window purge, when it arrives, amends THIS
+-- function (`CREATE OR REPLACE FUNCTION`) rather than adding a second, competing
+-- guard. Nothing here is a partial version of it: there is no age test and no
+-- column test to mistake for one.
+--
+-- TRUNCATE is NOT covered, and cannot be by a row trigger — it bypasses them
+-- entirely. Blocking it needs a BEFORE TRUNCATE statement trigger or, better,
+-- revoking the privilege from the application role, and it would break the test
+-- fixtures that reset the schema with `TRUNCATE ... CASCADE`. Out of scope here.
+CREATE OR REPLACE FUNCTION stackbone_platform.audit_log_refuse_mutation() RETURNS trigger
+LANGUAGE plpgsql AS $fn$
+BEGIN
+    RAISE EXCEPTION 'audit_log rows are immutable — % refused', TG_OP
+        USING ERRCODE = 'restrict_violation';
+END;
+$fn$;
+--> statement-breakpoint
+-- One trigger over both verbs so there is a single object to find and amend.
+-- BEFORE, so the refusal happens before any row is touched.
+DROP TRIGGER IF EXISTS audit_log_refuse_mutation_bud ON stackbone_platform.audit_log;
+--> statement-breakpoint
+CREATE TRIGGER audit_log_refuse_mutation_bud
+BEFORE UPDATE OR DELETE ON stackbone_platform.audit_log
+FOR EACH ROW EXECUTE FUNCTION stackbone_platform.audit_log_refuse_mutation();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbone/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
@@ -18,6 +18,8 @@
     "@bufbuild/protobuf": "^2.12.0",
     "@clack/prompts": "^1.2.0",
     "@hono/node-server": "^2.0.0",
+    "@hono/zod-openapi": "^1.6.1",
+    "@scalar/hono-api-reference": "^0.11.16",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "bullmq": "^5.76.6",