@jaguilar87/gaia 5.0.8 → 5.0.10

package/dist/gaia-security/hooks/modules/tools/bash_validator.py

@@ -911,6 +911,57 @@ class BashValidator:
             reason="Safe by elimination (not blocked, not mutative)",
         )
 
+    def _is_ungranted_t3_component(
+        self, component: str, session_id: str
+    ) -> bool:
+        """Classify a chain component as ungranted-T3 WITHOUT minting or consuming.
+
+        Returns True when the component is a T3 (mutative-verb or
+        flag-dependent) operation for which NO active grant exists -- i.e. the
+        component would, on its own, be blocked pending approval. This is a
+        read-only probe used by the chain COMMAND_SET intake (AC-8) to decide
+        whether >= 2 sub-commands need grouping under ONE consent, BEFORE any
+        per-component minting happens.
+
+        It deliberately does NOT call decide_t3_outcome (no pending minted) and
+        does NOT consume any grant (match_command_set_grant /
+        check_approval_grant are pure lookups; consumption happens later in the
+        real _validate_single_command pass at retry). A component that already
+        matches a COMMAND_SET or semantic grant is treated as NOT ungranted, so
+        it is excluded from a fresh batch.
+        """
+        component = component.strip()
+        if not component:
+            return False
+
+        # Is this T3 (mutative verb or flag-dependent mutation)?
+        detect = detect_mutative_command(component)
+        is_t3 = detect.is_mutative
+        if not is_t3:
+            flag_result = classify_by_flags(component)
+            if (
+                flag_result is not None
+                and flag_result.outcome == FLAG_MUTATIVE
+                and not flag_result.command_family.startswith("git_")
+            ):
+                is_t3 = True
+        if not is_t3:
+            return False
+
+        # Already covered by an active grant? Then it is NOT ungranted -- exclude
+        # it from a fresh batch (pure lookups, no consumption).
+        try:
+            if match_command_set_grant(component) is not None:
+                return False
+        except Exception:
+            pass
+        try:
+            if check_approval_grant(component, session_id=session_id) is not None:
+                return False
+        except Exception:
+            pass
+        return True
+
     def _validate_compound_command(
         self,
         components: List[str],
@@ -918,9 +969,68 @@ class BashValidator:
         session_id: str = "",
         agent_type: str = "",
     ) -> BashValidationResult:
-        """Validate a compound command (multiple components)."""
+        """Validate a compound command (multiple components).
+
+        Chain COMMAND_SET intake (AC-8): when a chain ``a && b && c`` has TWO OR
+        MORE sub-commands that are ungranted T3, classifying them one-at-a-time
+        mints a single-signature pending for the FIRST and short-circuits -- so
+        one approval covers only the first sub-command and the next re-blocks
+        (the double-approval the user hit). To group them, a NON-MINTING
+        classification pass runs FIRST (``_is_ungranted_t3_component``); if >= 2
+        sub-commands are ungranted-T3 (and we are a subagent under the
+        orchestrator), ONE COMMAND_SET pending is minted over exactly those T3
+        sub-commands via ``decide_t3_outcome(command_set=...)``. One approval
+        then covers the chain; each sub-command is still consumed byte-for-byte
+        by its own signature at retry (no consent is widened -- the commands are
+        only grouped). Critically, the per-component minting path
+        (_validate_single_command) is NEVER entered for the batch, so no stray
+        single pendings are minted alongside the COMMAND_SET.
+
+        For every other shape (0 or 1 ungranted-T3, no orchestrator above, or a
+        component that is hard-blocked) the original per-component pass runs
+        unchanged: a hard block fails the chain fast, a lone T3 keeps the
+        singular grant path, and an all-granted/safe chain is allowed.
+        """
         logger.info(f"Compound command detected with {len(components)} components")
 
+        # NON-MINTING pre-pass: which components are ungranted T3? (AC-8)
+        if is_subagent and is_ops_mode():
+            ungranted_t3_idx = [
+                idx
+                for idx, comp in enumerate(components)
+                if self._is_ungranted_t3_component(comp, session_id)
+            ]
+            if len(ungranted_t3_idx) >= 2:
+                chain_set = [
+                    {"command": components[idx].strip(), "rationale": ""}
+                    for idx in ungranted_t3_idx
+                ]
+                first_cmd = chain_set[0]["command"]
+                first_detect = detect_mutative_command(first_cmd)
+                verb = first_detect.verb or "command"
+                category = first_detect.category or "MUTATIVE"
+                native_ask_reason = (
+                    f"[T3_APPROVAL_REQUIRED] Chain of {len(chain_set)} T3 commands.\n"
+                    f"Commands:\n"
+                    + "\n".join(f"  - {it['command']}" for it in chain_set)
+                )
+                logger.info(
+                    "Chain COMMAND_SET intake: %d T3 sub-commands grouped under "
+                    "one consent (chain=%s)",
+                    len(chain_set),
+                    " && ".join(it["command"][:30] for it in chain_set),
+                )
+                return decide_t3_outcome(
+                    first_cmd,
+                    verb=verb,
+                    category=category,
+                    has_orchestrator_above=True,
+                    native_ask_reason=native_ask_reason,
+                    session_id=session_id,
+                    agent_type=agent_type,
+                    command_set=chain_set,
+                )
+
         component_results: List[BashValidationResult] = []
         for i, component in enumerate(components, 1):
             result = self._validate_single_command(
@@ -1385,6 +1495,7 @@ def decide_t3_outcome(
     native_ask_reason: str,
     session_id: str = "",
     agent_type: str = "",
+    command_set: list | None = None,
 ) -> BashValidationResult:
     """Single decision point for the outcome of a T3 (state-mutating) command.
 
@@ -1416,34 +1527,68 @@ def decide_t3_outcome(
         native_ask_reason: Reason text for the native-ask fallback branch.
         session_id: Session ID for pending-approval scoping.
         agent_type: Originating agent name (for the sealed payload).
+        command_set: Optional list of ``{command, rationale}`` dicts. When it
+            carries MORE THAN ONE item, this T3 decision covers a chain
+            (``a && b && c``) whose sub-commands are all T3, and the pending is
+            minted as ONE COMMAND_SET envelope (the chain-intake path, AC-8)
+            instead of a single semantic-signature pending. ONE user approval
+            then covers the whole chain; each sub-command is still consumed
+            byte-for-byte by its own signature at retry. A None / single-item
+            set keeps the singular behaviour. Only honoured in the
+            subagent-under-orchestrator branch (the native-ask branch has no
+            COMMAND_SET concept).
 
     Returns:
         A blocked BashValidationResult (allowed=False, tier T3) whose
         block_response is either a "deny" (with approval_id) or an "ask".
     """
+    # A genuine multi-command chain is a set of >= 2 items. Anything else
+    # collapses to the singular path so we never mint a COMMAND_SET for one
+    # command (mirrors _build_sealed_payload's is_command_set guard).
+    _normalized_set: list = []
+    if command_set:
+        for _item in command_set:
+            if isinstance(_item, dict) and _item.get("command"):
+                _normalized_set.append(
+                    {
+                        "command": _item["command"],
+                        "rationale": _item.get("rationale", ""),
+                    }
+                )
+    is_chain_command_set = len(_normalized_set) > 1
+
     if has_orchestrator_above:
         # Subagent-under-orchestrator: deny + persisted approval_id so the
         # orchestrator can run the approval cycle.  Reuse an existing pending
         # approval on retry to avoid generating duplicates while the user reviews.
-        approval_id = _find_pending_in_db(session_id or "", command)
-        if approval_id:
-            logger.info(
-                "Reusing pending approval_id=%s for retry: %s",
-                approval_id, command[:80],
-            )
-            reason = build_t3_blocked_denial_message(
-                approval_id=approval_id,
-                command=command,
-                verb=verb,
-                category=category,
-            )
-            hook_deny = build_hook_permission_response("deny", reason)
-            return BashValidationResult(
-                allowed=False,
-                tier=SecurityTier.T3_BLOCKED,
-                reason=f"T3 {category.lower()} command: {command[:60]}",
-                block_response=hook_deny,
-            )
+        #
+        # For a COMMAND_SET chain the pending id is CONTENT-derived (matching the
+        # plan-first intake), so a retry of the same chain produces the same id
+        # and the fingerprint-dedup in insert_requested reuses the pending. The
+        # singular reuse probe (_find_pending_in_db) matches a SINGLE command's
+        # signature and must NOT be consulted for the chain -- it would match one
+        # leftover single pending of a sub-command and degrade the chain back to
+        # a single grant. So the chain path skips it entirely.
+        if not is_chain_command_set:
+            approval_id = _find_pending_in_db(session_id or "", command)
+            if approval_id:
+                logger.info(
+                    "Reusing pending approval_id=%s for retry: %s",
+                    approval_id, command[:80],
+                )
+                reason = build_t3_blocked_denial_message(
+                    approval_id=approval_id,
+                    command=command,
+                    verb=verb,
+                    category=category,
+                )
+                hook_deny = build_hook_permission_response("deny", reason)
+                return BashValidationResult(
+                    allowed=False,
+                    tier=SecurityTier.T3_BLOCKED,
+                    reason=f"T3 {category.lower()} command: {command[:60]}",
+                    block_response=hook_deny,
+                )
 
         # No existing pending -- insert via DB (D16: exclusive path).
         sealed_payload = _build_sealed_payload(
@@ -1451,13 +1596,25 @@ def decide_t3_outcome(
             verb=verb,
             category=category,
             agent_type=agent_type,
+            command_set=_normalized_set if is_chain_command_set else None,
         )
         try:
             from gaia.approvals.store import insert_requested
+            # COMMAND_SET chains use a CONTENT-derived id (deterministic over the
+            # sub-command list) so a retry of the same chain reproduces the same
+            # id and reuses the pending via fingerprint dedup -- identical to the
+            # plan-first intake in handoff_persister. Singular T3 keeps uuid4.
+            supplied_id = None
+            if is_chain_command_set:
+                from gaia.approvals.store import derive_command_set_id
+                supplied_id = derive_command_set_id(
+                    [it["command"] for it in _normalized_set]
+                )
             approval_id = insert_requested(
                 sealed_payload,
                 agent_id=agent_type or None,
                 session_id=session_id or None,
+                approval_id=supplied_id,
             )
         except Exception as _store_err:
             logger.warning(

package/dist/gaia-security/hooks/user_prompt_submit.py

@@ -194,6 +194,26 @@ if __name__ == "__main__":
             else:
                 logger.info("Could not extract user prompt from stdin, skipping routing")
 
+            # Per-turn VERIFIED pending approvals. Lets the orchestrator present
+            # a pending approval for consent directly from injected context,
+            # WITHOUT dispatching a subagent to derive/verify it (that dispatch's
+            # SubagentStop caused a pending-revocation bug). Emits "" when there
+            # are no verified pendings, so a turn with nothing pending injects
+            # nothing -- this is what keeps the per-turn injection quiet, unlike
+            # the one-shot SessionStart summary it deliberately does not re-emit.
+            try:
+                from modules.session.session_manifest import (
+                    build_per_turn_pending_approvals_block,
+                )
+                pending_block = build_per_turn_pending_approvals_block()
+                if pending_block:
+                    context_parts.append(pending_block)
+            except Exception as _pa_exc:
+                logger.debug(
+                    "per-turn pending approvals injection failed (non-fatal): %s",
+                    _pa_exc,
+                )
+
         additional_context = "\n\n".join(context_parts)
         logger.info("Context injected: %s mode (%d chars)", mode, len(additional_context))
 

package/gaia/approvals/store.py

@@ -29,8 +29,16 @@ Public API::
     reject(approval_id, approver_session, *, agent_id=None, con=None)
         -> None  -- convenience wrapper: pending -> rejected
 
+    revoke(approval_id, revoker_session, *, agent_id=None, event_payload=None,
+           metadata_json=None, con=None)
+        -> None  -- convenience wrapper: pending -> revoked (user/admin cancel)
+
+    expire(approval_id, expirer_session=None, *, agent_id=None,
+           event_payload=None, metadata_json=None, con=None)
+        -> None  -- convenience wrapper: pending -> expired (TTL-sweep terminal)
+
     transition(approval_id, from_status, to_status, event_payload, *,
-               agent_id, session_id, con=None)
+               agent_id, session_id, metadata_json=None, con=None)
         -> None  -- state machine wrapper; raises if from_status does not match
 
     replay_for_approval(approval_id, con=None)
@@ -500,6 +508,7 @@ def transition(
     *,
     agent_id: Optional[str] = None,
     session_id: Optional[str] = None,
+    metadata_json: Optional[str] = None,
     con: Optional[sqlite3.Connection] = None,
 ) -> None:
     """State machine wrapper for approval status transitions.
@@ -512,21 +521,34 @@ def transition(
         approval_id: The P-{uuid4} approval identifier.
         from_status: Expected current status (guard). Must match the actual
             stored status or this function raises ValueError.
-        to_status: New status to write.
+        to_status: New status to write. Recognized: 'approved', 'rejected',
+            'revoked', 'expired'. The 'expired' status is the TTL-sweep
+            terminal status (schema.sql, bu_approvals_status_has_event excludes
+            it); it has no dedicated event_type in approval_events, so its audit
+            event is recorded as a REVOKED event carrying a reason in
+            metadata_json to distinguish a TTL expiry from a user/admin revoke.
         event_payload: Optional dict for the event's payload_json and fingerprint.
-        agent_id: Optional agent identifier for the event.
+        agent_id: Optional agent identifier for the event -- restores provenance
+            on auto-transitions (cleanup/expiry) that previously wrote null.
         session_id: Optional session identifier for the event.
+        metadata_json: Optional free-form JSON forwarded to the event's
+            metadata_json column (e.g. {"reason": "expired_ttl", ...}). Mirrors
+            record_event(); the canonical way to tag WHY an auto-transition fired.
         con: Optional open connection.
 
     Raises:
         ValueError: If the stored status does not match from_status.
         ValueError: If the approval_id does not exist.
     """
-    # Derive the event_type from the to_status transition.
+    # Derive the event_type from the to_status transition. 'expired' has no
+    # event_type of its own (the approval_events CHECK has no EXPIRED value and
+    # the status-has-event trigger does not gate it), so its audit trail is a
+    # REVOKED event distinguished by metadata_json reason="expired_ttl".
     _STATUS_TO_EVENT: dict[str, str] = {
         "approved": "APPROVED",
         "rejected": "REJECTED",
         "revoked": "REVOKED",
+        "expired": "REVOKED",
     }
     event_type = _STATUS_TO_EVENT.get(to_status, to_status.upper())
 
@@ -549,10 +571,10 @@ def transition(
                 f"Cannot transition approval {approval_id!r}: "
                 f"expected status={from_status!r} but found {actual_status!r}"
             )
-        _con.execute(
-            "UPDATE approvals SET status = ?, decided_at = ? WHERE id = ?",
-            (to_status, _now_iso(), approval_id),
-        )
+        # Insert the event FIRST so the DB trigger bu_approvals_status_has_event
+        # (schema.sql) can verify the event exists before the status UPDATE fires.
+        # The trigger fires BEFORE UPDATE, reading the transaction-visible
+        # approval_events rows; inserting the event first satisfies the guard.
         insert_event(
             _con,
             approval_id,
@@ -561,6 +583,11 @@ def transition(
             session_id=session_id,
             payload_json=payload_json_str,
             fingerprint=fp,
+            metadata_json=metadata_json,
+        )
+        _con.execute(
+            "UPDATE approvals SET status = ?, decided_at = ? WHERE id = ?",
+            (to_status, _now_iso(), approval_id),
         )
         if owned:
             _con.commit()
@@ -610,6 +637,8 @@ def revoke(
     revoker_session: str,
     *,
     agent_id: Optional[str] = None,
+    event_payload: Optional[Dict[str, Any]] = None,
+    metadata_json: Optional[str] = None,
     con: Optional[sqlite3.Connection] = None,
 ) -> None:
     """Revoke a pending approval (user or admin cancellation before execution).
@@ -621,7 +650,11 @@ def revoke(
     Args:
         approval_id: The P-{uuid4} approval identifier.
         revoker_session: The session_id of the revoking session.
-        agent_id: Optional agent identifier for the REVOKED event.
+        agent_id: Optional agent identifier for the REVOKED event -- pass this on
+            automated revocations so the event carries provenance instead of null.
+        event_payload: Optional dict for the event's payload_json and fingerprint.
+        metadata_json: Optional free-form JSON tagging WHY the revoke fired
+            (e.g. {"reason": "...", "source": "..."}), forwarded to the event.
         con: Optional open connection.
 
     Raises:
@@ -632,8 +665,53 @@ def revoke(
         approval_id,
         from_status="pending",
         to_status="revoked",
+        event_payload=event_payload,
         agent_id=agent_id,
         session_id=revoker_session,
+        metadata_json=metadata_json,
+        con=con,
+    )
+
+
+def expire(
+    approval_id: str,
+    expirer_session: Optional[str] = None,
+    *,
+    agent_id: Optional[str] = None,
+    event_payload: Optional[Dict[str, Any]] = None,
+    metadata_json: Optional[str] = None,
+    con: Optional[sqlite3.Connection] = None,
+) -> None:
+    """Expire a pending approval whose TTL has elapsed (cleanup-layer sweep).
+
+    Transitions approvals.status to 'expired' -- the schema's TTL-sweep terminal
+    status (schema.sql). 'expired' is deliberately distinct from 'revoked': a
+    revoke is a user/admin cancellation, an expire is the 24h pending window
+    (DEFAULT_PENDING_TTL_MINUTES) lapsing without a decision. Because the
+    approval_events schema has no EXPIRED event_type and the status-has-event
+    trigger does not gate 'expired', the audit event is recorded as REVOKED and
+    distinguished by metadata_json (reason="expired_ttl").
+
+    Args:
+        approval_id: The P-{uuid4} approval identifier.
+        expirer_session: The session_id under which the sweep ran (event session).
+        agent_id: Optional agent identifier for the event (provenance).
+        event_payload: Optional dict for the event's payload_json and fingerprint.
+        metadata_json: Optional free-form JSON tagging the expiry reason.
+        con: Optional open connection.
+
+    Raises:
+        ValueError: If the approval is not in 'pending' status.
+        ValueError: If the approval_id does not exist.
+    """
+    transition(
+        approval_id,
+        from_status="pending",
+        to_status="expired",
+        event_payload=event_payload,
+        agent_id=agent_id,
+        session_id=expirer_session,
+        metadata_json=metadata_json,
         con=con,
     )
 

package/gaia/briefs/__init__.py

@@ -31,6 +31,8 @@ from gaia.briefs.store import (
     upsert_brief,
     list_briefs,
     get_brief,
+    get_brief_by_id,
+    find_brief_workspaces,
     close_brief,
     get_dependencies,
     search_briefs,
@@ -49,6 +51,8 @@ __all__ = [
     "upsert_brief",
     "list_briefs",
     "get_brief",
+    "get_brief_by_id",
+    "find_brief_workspaces",
     "close_brief",
     "get_dependencies",
     "search_briefs",

package/gaia/briefs/store.py

@@ -268,6 +268,97 @@ def list_briefs(
 # get_brief
 # ---------------------------------------------------------------------------
 
+def get_brief_by_id(
+    brief_id: int,
+    *,
+    db_path: Path | None = None,
+) -> dict | None:
+    """Return the full brief dict by numeric primary key, or None.
+
+    Like :func:`get_brief` but resolves by ``id`` instead of
+    ``(workspace, name)``. Used by ``gaia brief show <int>`` so users can
+    look up a brief by its DB id without knowing which workspace it lives in.
+    """
+    con = _connect(db_path)
+    try:
+        row = con.execute(
+            "SELECT * FROM briefs WHERE id = ?",
+            (brief_id,),
+        ).fetchone()
+        if row is None:
+            return None
+
+        brief: dict[str, Any] = dict(row)
+        brief.pop("workspace", None)
+
+        ac_rows = con.execute(
+            "SELECT ac_id, description, evidence_type, evidence_shape, artifact_path "
+            "FROM acceptance_criteria WHERE brief_id = ? ORDER BY id",
+            (brief["id"],),
+        ).fetchall()
+        acs: list[dict] = []
+        for ar in ac_rows:
+            shape = ar["evidence_shape"]
+            if shape:
+                try:
+                    shape = json.loads(shape)
+                except Exception:
+                    pass
+            acs.append({
+                "ac_id": ar["ac_id"],
+                "description": ar["description"],
+                "evidence_type": ar["evidence_type"],
+                "evidence_shape": shape,
+                "artifact_path": ar["artifact_path"],
+            })
+        brief["acceptance_criteria"] = acs
+
+        ms_rows = con.execute(
+            "SELECT order_num, name, description FROM milestones "
+            "WHERE brief_id = ? ORDER BY order_num",
+            (brief["id"],),
+        ).fetchall()
+        brief["milestones"] = [
+            {"order_num": m["order_num"], "name": m["name"],
+             "description": m["description"]}
+            for m in ms_rows
+        ]
+
+        dep_rows = con.execute(
+            "SELECT b2.name FROM brief_dependencies bd "
+            "JOIN briefs b2 ON b2.id = bd.depends_on_id "
+            "WHERE bd.brief_id = ? ORDER BY b2.name",
+            (brief["id"],),
+        ).fetchall()
+        brief["dependencies"] = [r["name"] for r in dep_rows]
+
+        return brief
+    finally:
+        con.close()
+
+
+def find_brief_workspaces(
+    name: str,
+    *,
+    db_path: Path | None = None,
+) -> list[str]:
+    """Return all workspace names that contain a brief with the given slug.
+
+    Used by ``gaia brief show`` to emit a helpful cross-workspace hint when
+    a brief is not found in the resolved workspace.  Returns an empty list
+    when no brief with that name exists anywhere.
+    """
+    con = _connect(db_path)
+    try:
+        rows = con.execute(
+            "SELECT workspace FROM briefs WHERE name = ? ORDER BY workspace",
+            (name,),
+        ).fetchall()
+        return [r["workspace"] for r in rows]
+    finally:
+        con.close()
+
+
 def get_brief(
     workspace: str,
     name: str,

package/gaia/store/schema.sql

@@ -785,7 +785,9 @@ CREATE TABLE IF NOT EXISTS approval_grants (
     status               TEXT NOT NULL DEFAULT 'PENDING',  -- PENDING|CONSUMED|REVOKED|EXPIRED
     consumed_indexes_json TEXT,                      -- JSON array of consumed command_set indexes
     consumed_at          TEXT,                       -- ISO8601 when all items consumed
-    revoked_at           TEXT                        -- ISO8601 when explicitly revoked
+    revoked_at           TEXT,                       -- ISO8601 when explicitly revoked
+    multi_use            INTEGER NOT NULL DEFAULT 0, -- 1 = multi-use grant, 0 = single-use (BOOLEAN)
+    confirmed            INTEGER NOT NULL DEFAULT 0  -- 1 = grant confirmed by user, 0 = pending (BOOLEAN)
 );
 
 CREATE INDEX IF NOT EXISTS idx_approval_grants_agent   ON approval_grants(agent_id);
@@ -950,6 +952,41 @@ BEGIN
     SELECT RAISE(ABORT, 'approval_events is append-only');
 END;
 
+-- BEFORE UPDATE trigger: enforce that every approvals.status transition has a
+-- preceding event in the append-only approval_events chain (Task B audit-
+-- immutability gap closure).
+--
+-- Fires when status changes TO one of the three user-visible terminal statuses
+-- (approved / rejected / revoked). For each new status it checks that an event
+-- row with the matching event_type exists for this approval_id. Because the
+-- canonical write path (store.transition) inserts the event FIRST and then
+-- UPDATEs status, the event row is already in the transaction-visible table by
+-- the time this trigger fires -- and the check passes. A direct UPDATE that
+-- bypasses the write path (no preceding insert_event call) will find COUNT=0
+-- and RAISE(ABORT), rolling back the update.
+--
+-- 'expired' is intentionally excluded: it is a cleanup-layer status (TTL
+-- sweep) with no corresponding event_type in the approval_events schema. All
+-- other status values ('pending') are only ever written by INSERT in
+-- insert_requested(), not by UPDATE, so they are not reachable here.
+CREATE TRIGGER IF NOT EXISTS bu_approvals_status_has_event
+BEFORE UPDATE OF status ON approvals
+WHEN NEW.status != OLD.status AND NEW.status IN ('approved', 'rejected', 'revoked')
+BEGIN
+    SELECT CASE
+        WHEN (
+            SELECT COUNT(*) FROM approval_events
+             WHERE approval_id = NEW.id
+               AND event_type = CASE NEW.status
+                                    WHEN 'approved' THEN 'APPROVED'
+                                    WHEN 'rejected' THEN 'REJECTED'
+                                    WHEN 'revoked'  THEN 'REVOKED'
+                                END
+        ) = 0
+        THEN RAISE(ABORT, 'approvals: status change requires a preceding event in approval_events')
+    END;
+END;
+
 -- ---------------------------------------------------------------------------
 -- schema_version: migration ledger.
 -- One row per applied schema migration; the highest version is the current