Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

243 KB
Raw Blame
"""CRUD + resolve + grants + audit over the vault tables.

Data layer for Vaults, sibling to ``storage/messages_service.py`` etc.: functions take
a SQLAlchemy ``Connection`` and never open their own engine. This module owns the
metadata invariants around stored envelopes, approval requests, grants, and audit
rows so future vault behavior lands here rather than in callers.

Secret values and key material never live here. Standard-tier values are sealed by
``avault`` before this layer stores them. Protected-tier values arrive already
encrypted by the browser; this layer only stores the opaque ciphertext + wrap
metadata. Grants persist metadata only; protected delivery material is owned by
the resident avault agent, not by Python.
"""

from __future__ import annotations

import json
import logging
import re
import secrets
import threading
import uuid
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from functools import lru_cache
from pathlib import Path
from typing import Any
from urllib.parse import urlsplit

from sqlalchemy import and_, func, or_, select, tuple_
from sqlalchemy.dialects.sqlite import insert as sqlite_insert
from sqlalchemy.engine import Connection
from sqlalchemy.exc import IntegrityError

from storage import vault_crypto, vault_webauthn
from storage.lock import LockHolderState, MigrationFileLock, probe_lock_holder, remove_unheld_lock
from storage.models import (
    agent_sessions,
    scopes,
    state_meta,
    vault_audit,
    vault_auth_factors,
    vault_grants,
    vault_operation_challenges,
    vault_requests,
    vault_secrets,
    message_deliveries,
    session_turns,
)
from storage.vault_addresses import derive_addresses
from storage.vault_crypto import Sealed
logger = logging.getLogger(__name__)

SKILL_TAG_PREFIX = "skill:"
VAULT_SETTINGS_META_KEY = "vault_settings"
PROTECTED_VAULT_ESTABLISHMENT_LOCK_META_KEY = "vault_protected_establishment_lock"
DEFAULT_UNLOCK_WINDOW_SECONDS = 600
UNLOCK_WINDOW_OPTIONS_SECONDS = (300, 600, 1800)
GRANT_DURATION_ONE_TIME = "one-time"
ONE_TIME_GRANT_TTL_SECONDS = 60
DEFAULT_GRANT_TTL_SECONDS = 300
GRANT_TTL_OPTIONS_SECONDS = (300, 900)
LAST_GRANT_TTL_OPTIONS = (GRANT_DURATION_ONE_TIME, *GRANT_TTL_OPTIONS_SECONDS)
DEFAULT_AUTHZ_CHALLENGE_TTL_SECONDS = 120
DEFAULT_REQUEST_TTL_SECONDS = 30 * 60
AUTH_FACTOR_REGISTRATION_AUTHZ_OPERATION = "authorize_webauthn_factor_registration"
GRANT_PURPOSES = {"run", "fetch", "inject"}
SUPPORTED_SIGNATURE_SCHEMES = {
    "ecdsa-secp256k1-recoverable",
    "ecdsa-secp256k1-der",
    "schnorr-secp256k1-bip340",
}
REQUEST_AUDIENCE_AGENT = "agent"
REQUEST_AUDIENCE_UI = "ui"
REQUEST_AUDIENCES = {REQUEST_AUDIENCE_AGENT, REQUEST_AUDIENCE_UI}
_AUDIT_ACCESS_SNAPSHOT_KEY = "_resource_access_snapshot"
_REMOTE_AUDIT_MIN_BATCH_SIZE = 25
_REMOTE_AUDIT_MAX_BATCH_SIZE = 200
PROVISION_SPEC_FORBIDDEN_KEYS = {
    "value",
    "sealed",
    "envelope",
    "blind_box",
    "ciphertext",
    "nonce",
    "wrap_meta",
    "private_key",
    "secret",
}
PROVISION_SPEC_ALLOWED_KEYS = {
    "kind",
    "protection",
    "description",
    "tags",
    "policy",
    "links",
    "fields",
    "default_field",
}
PROVISION_FIELD_NAME_RE = re.compile(r"^[a-z][a-z0-9_]{0,63}$")
MAX_SECRET_FIELDS = 32
PROVISION_SPEC_ALLOWED_POLICY_KEYS = {"allowed_hosts", "auth"}
PROVISION_SPEC_ALLOWED_AUTH_KEYS = {"type", "name"}
FETCH_AUTH_HEADER_NAME_RE = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$")
FETCH_AUTH_QUERY_NAME_RE = re.compile(r"^[A-Za-z0-9._~-]+$")
FORBIDDEN_FETCH_AUTH_HEADER_NAMES = frozenset({"host"})
_UNSET = object()


@dataclass(frozen=True)
class DeliveryIdentity:
    """Value-free pre-handoff identity retained for post-delivery bookkeeping."""

    secret_id: str
    name: str
    field: str
    access_snapshot: dict[str, Any] | None


@dataclass(frozen=True)
class GrantApproval:
    grant_id: str
    members: list[str]
    session_id: str | None
    source_selector: dict[str, Any]
    purpose: str
    one_shot: bool
    ttl_cap_seconds: int


@dataclass(frozen=True)
class RequestGrantOption:
    grant_id: str
    members: list[str]
    source_selector: dict[str, Any]
    purpose: str
    one_shot: bool
    ttl_cap_seconds: int


@dataclass(frozen=True)
class GrantReadiness:
    active: bool
    persisted_agent_ready: bool
    runtime_agent_ready: bool
    standard_ready: bool
    delivery_ready: bool
    delivery_status: str


@dataclass(frozen=True)
class CardHydrationPolicy:
    audience: str
    include_protected_unlock_material: bool


class VaultServiceError(Exception):
    """Base class for vault data-layer errors."""


class InvalidSecretNameError(VaultServiceError):
    pass


class SecretExistsError(VaultServiceError):
    pass


class InvalidFieldNameError(VaultServiceError):
    pass


class FieldExistsError(VaultServiceError):
    pass


class FieldNotFoundError(VaultServiceError):
    pass


class TooManyFieldsError(VaultServiceError):
    pass


class FieldsNotSupportedError(VaultServiceError):
    pass


class FieldsCorruptError(VaultServiceError):
    pass


class RecordMismatchError(VaultServiceError):
    pass


class SecretConflictError(VaultServiceError):
    pass


class SecretNameCaseConflictError(VaultServiceError):
    def __init__(self, name: str, existing_name: str):
        self.name = name
        self.existing_name = existing_name
        super().__init__(f"secret name {name!r} conflicts with existing name {existing_name!r}")


class SecretNotFoundError(VaultServiceError):
    pass


class VaultSecretAccessError(VaultServiceError):
    """Raised when the current caller cannot use a Vault secret."""


class RequestNotFoundError(VaultServiceError):
    pass


class InvalidRequestError(VaultServiceError):
    pass


class UnsupportedProtectionError(VaultServiceError):
    """A caller attempted the wrong delivery path for a protection tier."""


class KeypairNotValueDeliverableError(VaultServiceError):
    """A signing key was requested through a value-delivery path."""


class InvalidGrantError(VaultServiceError):
    pass


class GrantNotFoundError(VaultServiceError):
    pass


class GrantNotActiveError(VaultServiceError):
    pass


class NotGrantableError(VaultServiceError):
    pass


class VaultAlreadyInitializedError(VaultServiceError):
    pass


class SecretNotProtectedError(VaultServiceError):
    pass


class ProtectedAuthRequiredError(VaultServiceError):
    pass


class ProtectedAuthzSetupRequiredError(VaultServiceError):
    pass


class InvalidProtectedAuthzError(VaultServiceError):
    pass


class VaultGrantRuntimeCache:
    """Process-local grant delivery readiness tracker.

    This intentionally stores no DEKs, plaintext, or browser-unwrapped key material.
    The resident avault agent owns the actual DEK cache; this cache only remembers
    which persisted grant rows should be deliverable through that agent process.
    """

    def __init__(self) -> None:
        self._lock = threading.RLock()
        self._members_by_grant: dict[str, set[str]] = {}
        self._expires_at_by_grant: dict[str, datetime] = {}
        self._timers_by_grant: dict[str, threading.Timer] = {}

    def put(self, grant_id: str, members: list[str] | set[str], *, expires_at: str | None = None) -> None:
        expires_at_dt = _parse_iso_datetime(expires_at)
        with self._lock:
            self._drop_locked(grant_id)
            if expires_at_dt is not None and expires_at_dt <= datetime.now(timezone.utc):
                return
            self._members_by_grant[grant_id] = set(members)
            if expires_at_dt is not None:
                self._expires_at_by_grant[grant_id] = expires_at_dt
                delay = max(0.0, (expires_at_dt - datetime.now(timezone.utc)).total_seconds())
                timer = threading.Timer(delay, self.drop, args=(grant_id,))
                timer.daemon = True
                self._timers_by_grant[grant_id] = timer
                timer.start()

    def has(self, grant_id: str, secret_name: str) -> bool:
        with self._lock:
            self._drop_if_expired_locked(grant_id)
            return secret_name in self._members_by_grant.get(grant_id, set())

    def get(self, grant_id: str, secret_name: str) -> str | None:
        """No Python-owned protected key material is available from this cache."""
        with self._lock:
            self._drop_if_expired_locked(grant_id)
            return None

    def covered_names(self, grant_id: str) -> list[str]:
        with self._lock:
            self._drop_if_expired_locked(grant_id)
            return sorted(self._members_by_grant.get(grant_id, set()))

    def drop(self, grant_id: str) -> None:
        with self._lock:
            self._drop_locked(grant_id)

    def clear(self) -> None:
        with self._lock:
            for timer in self._timers_by_grant.values():
                timer.cancel()
            self._members_by_grant.clear()
            self._expires_at_by_grant.clear()
            self._timers_by_grant.clear()

    def _drop_locked(self, grant_id: str) -> None:
        self._members_by_grant.pop(grant_id, None)
        self._expires_at_by_grant.pop(grant_id, None)
        timer = self._timers_by_grant.pop(grant_id, None)
        if timer is not None:
            timer.cancel()

    def _drop_if_expired_locked(self, grant_id: str) -> None:
        expires_at = self._expires_at_by_grant.get(grant_id)
        if expires_at is not None and expires_at <= datetime.now(timezone.utc):
            self._drop_locked(grant_id)


GRANT_RUNTIME_CACHE = VaultGrantRuntimeCache()


def _now() -> str:
    return datetime.now(timezone.utc).isoformat()


def _request_expiry(ttl_seconds: int = DEFAULT_REQUEST_TTL_SECONDS) -> str:
    return (datetime.now(timezone.utc) + timedelta(seconds=ttl_seconds)).isoformat()


def _parse_iso_datetime(value: str | None) -> datetime | None:
    if not value:
        return None
    try:
        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
    except ValueError:
        return None
    if parsed.tzinfo is None:
        return parsed.replace(tzinfo=timezone.utc)
    return parsed.astimezone(timezone.utc)


def _next_updated_at(previous: str | None = None) -> str:
    current = datetime.now(timezone.utc)
    previous_dt = _parse_iso_datetime(previous)
    if previous_dt is not None and current <= previous_dt:
        current = previous_dt + timedelta(microseconds=1)
    return current.isoformat()


def _id(prefix: str) -> str:
    return f"{prefix}_{uuid.uuid4().hex[:12]}"


def _default_vault_settings() -> dict[str, Any]:
    return {
        "unlock_window_seconds": DEFAULT_UNLOCK_WINDOW_SECONDS,
        "strict_approvals": False,
        "last_grant_ttl": DEFAULT_GRANT_TTL_SECONDS,
    }


def _normalize_unlock_window_seconds(value: Any) -> int:
    try:
        seconds = int(value)
    except (TypeError, ValueError) as exc:
        raise VaultServiceError("unlock_window_seconds must be one of 300, 600, or 1800") from exc
    if seconds not in UNLOCK_WINDOW_OPTIONS_SECONDS:
        raise VaultServiceError("unlock_window_seconds must be one of 300, 600, or 1800")
    return seconds


def normalize_grant_duration(value: Any | None, *, default: Any | None = None) -> dict[str, Any]:
    raw = default if value is None else value
    if raw is None:
        raw = DEFAULT_GRANT_TTL_SECONDS
    if isinstance(raw, str):
        normalized = raw.strip().lower().replace("_", "-")
        if normalized == GRANT_DURATION_ONE_TIME:
            return {
                "last_grant_ttl": GRANT_DURATION_ONE_TIME,
                "ttl_seconds": ONE_TIME_GRANT_TTL_SECONDS,
                "one_shot": True,
            }
        try:
            raw = int(normalized)
        except ValueError as exc:
            raise InvalidGrantError("grant duration must be one-time, 300, or 900 seconds") from exc
    try:
        ttl = int(raw)
    except (TypeError, ValueError) as exc:
        raise InvalidGrantError("grant duration must be one-time, 300, or 900 seconds") from exc
    if ttl not in GRANT_TTL_OPTIONS_SECONDS:
        raise InvalidGrantError("grant duration must be one-time, 300, or 900 seconds")
    return {"last_grant_ttl": ttl, "ttl_seconds": ttl, "one_shot": False}


def _normalize_last_grant_ttl(value: Any) -> str | int:
    return normalize_grant_duration(value)["last_grant_ttl"]


def _normalize_strict_approvals(value: Any) -> bool:
    if type(value) is not bool:
        raise VaultServiceError("strict_approvals must be a boolean")
    return value


def _normalize_vault_settings(raw: Any) -> dict[str, Any]:
    settings = _default_vault_settings()
    if isinstance(raw, dict):
        if "unlock_window_seconds" in raw:
            settings["unlock_window_seconds"] = _normalize_unlock_window_seconds(raw["unlock_window_seconds"])
        if "strict_approvals" in raw:
            settings["strict_approvals"] = _normalize_strict_approvals(raw["strict_approvals"])
        if "last_grant_ttl" in raw:
            settings["last_grant_ttl"] = _normalize_last_grant_ttl(raw["last_grant_ttl"])
    return settings


def get_vault_settings(conn: Connection) -> dict[str, Any]:
    raw = conn.execute(
        select(state_meta.c.value_json).where(state_meta.c.key == VAULT_SETTINGS_META_KEY)
    ).scalar_one_or_none()
    return _normalize_vault_settings(_loads(raw))


def save_vault_settings(conn: Connection, payload: dict[str, Any], *, user_context: Any = None) -> dict[str, Any]:
    if not isinstance(payload, dict):
        raise VaultServiceError("vault settings payload must be an object")
    # Instance-wide protection is management-only; approvers may still remember a grant TTL.
    # Check the whole payload before writing so mixed updates cannot partially succeed.
    if "unlock_window_seconds" in payload or "strict_approvals" in payload:
        context = resolve_resource_access_context(user_context)
        if not context.can_manage_instance:
            raise VaultSecretAccessError("Vault settings access is not permitted.")
    current = get_vault_settings(conn)
    updates: dict[str, Any] = {}
    if "unlock_window_seconds" in payload:
        updates["unlock_window_seconds"] = _normalize_unlock_window_seconds(payload["unlock_window_seconds"])
    if "strict_approvals" in payload:
        updates["strict_approvals"] = _normalize_strict_approvals(payload["strict_approvals"])
    if "last_grant_ttl" in payload:
        updates["last_grant_ttl"] = _normalize_last_grant_ttl(payload["last_grant_ttl"])
    next_settings = _normalize_vault_settings({**current, **updates})
    value_json = json.dumps(next_settings, sort_keys=True)
    now = _now()
    stmt = sqlite_insert(state_meta).values(
        key=VAULT_SETTINGS_META_KEY,
        value_json=value_json,
        updated_at=now,
    )
    conn.execute(
        stmt.on_conflict_do_update(
            index_elements=[state_meta.c.key],
            set_={
                "value_json": value_json,
                "updated_at": now,
            },
        )
    )
    return next_settings


def vault_session_policy(settings: dict[str, Any] | None = None) -> dict[str, Any]:
    normalized = _normalize_vault_settings(settings or {})
    return {
        "windowSeconds": normalized["unlock_window_seconds"],
        "strictApprovals": normalized["strict_approvals"],
        "parentValueSealAllowed": True,
    }


def _secret_name_case_key(name: str) -> str:
    # Secret names are ASCII shell identifiers, so SQL lower() and Python lower()
    # have the same case-folding behavior for the enforced domain.
    return name.lower()


def _find_secret_name_case_insensitive(conn: Connection, name: str) -> str | None:
    return conn.execute(
        select(vault_secrets.c.name)
        .where(func.lower(vault_secrets.c.name) == _secret_name_case_key(name))
        .limit(1)
    ).scalar_one_or_none()


def _find_pending_provision_name_case_insensitive(conn: Connection, name: str) -> str | None:
    return conn.execute(
        select(vault_requests.c.secret_name)
        .where(
            vault_requests.c.request_type == "provision",
            vault_requests.c.status == "pending",
            func.lower(vault_requests.c.secret_name) == _secret_name_case_key(name),
        )
        .order_by(vault_requests.c.created_at.desc(), vault_requests.c.id.desc())
        .limit(1)
    ).scalar_one_or_none()


def _preflight_secret_create_name(
    conn: Connection,
    *,
    name: str,
    provision_request_id: str | None = None,
) -> tuple[dict[str, Any] | None, bool]:
    existing_name = _find_secret_name_case_insensitive(conn, name)
    existing_secret = existing_name == name
    if existing_name is not None and existing_name != name:
        raise SecretNameCaseConflictError(name, existing_name)
    provision_row: dict[str, Any] | None = None
    if provision_request_id:
        _expire_pending_requests(conn)
        provision_row = _load_request_row(conn, provision_request_id)
        if provision_row.get("request_type") != "provision":
            raise InvalidRequestError("secret create must complete a provision request")
        if provision_row.get("secret_name") != name:
            raise InvalidRequestError("provision request secret name does not match")
        if provision_row.get("status") == "expired":
            raise InvalidRequestError("provision request has expired")
        if provision_row.get("status") == "fulfilled" and existing_secret:
            raise SecretExistsError(name)
        if provision_row.get("status") != "pending":
            raise InvalidRequestError("provision request is not pending")
    pending_name = _find_pending_provision_name_case_insensitive(conn, name)
    if pending_name is not None and pending_name != name:
        raise SecretNameCaseConflictError(name, pending_name)
    if existing_secret:
        raise SecretExistsError(name)
    return provision_row, bool(existing_secret)


def preflight_secret_create(
    conn: Connection,
    *,
    name: str,
    provision_request_id: str | None = None,
) -> None:
    """Validate name/request conflicts before a caller performs expensive sealing."""

    if not vault_crypto.is_valid_secret_name(name):
        raise InvalidSecretNameError(name)
    _preflight_secret_create_name(conn, name=name, provision_request_id=provision_request_id)


def _loads(raw: str | None) -> Any:
    if not raw:
        return None
    try:
        return json.loads(raw)
    except (TypeError, ValueError):
        return None


def _public_meta(raw: str | None) -> dict[str, Any]:
    payload = _loads(raw)
    return payload if isinstance(payload, dict) else {}


def _validate_field_name(name: Any, *, field: str = "field") -> str:
    if not isinstance(name, str) or not PROVISION_FIELD_NAME_RE.fullmatch(name):
        raise InvalidFieldNameError(f"{field} must match ^[a-z][a-z0-9_]{{0,63}}$")
    return name


def _default_field_name(row: dict[str, Any] | None = None, value: Any = None) -> str:
    if row is not None and row.get("kind") == "keypair":
        return "value"
    candidate = value
    if candidate is None and row is not None:
        candidate = _public_meta(row.get("public_meta")).get("default_field")
    try:
        return _validate_field_name(candidate or "value", field="default_field")
    except InvalidFieldNameError:
        return "value"


@lru_cache(maxsize=512)
def _warn_corrupt_fields(name: str, secret_id: str, updated_at: str) -> None:
    """Bounded warning cache: repeated reads of one damaged revision stay quiet."""
    logger.warning("Vault secret %s has corrupt fields; extra records and field mutations are unavailable", name)


def _extra_field_rows(row: dict[str, Any] | None, *, strict: bool = False) -> list[dict[str, Any]]:
    """Read the complete optional section, never a lossy partial projection.

    Default-record reads remain available when extras are corrupt. Any caller
    that writes fields or needs an extra record must fail closed instead.
    """
    if not row or row.get("fields") is None:
        return []
    try:
        raw = json.loads(row["fields"])
        if not isinstance(raw, list) or len(raw) >= MAX_SECRET_FIELDS:
            raise ValueError("invalid field array")
        seen = {_default_field_name(row)}
        if row.get("kind") == "keypair" and raw:
            raise ValueError("keypair has extra fields")
        for item in raw:
            if not isinstance(item, dict):
                raise ValueError("invalid field entry")
            name = _validate_field_name(item.get("name"))
            if name in seen:
                raise ValueError("duplicate field label")
            if not all(isinstance(item.get(key), str) and item[key] for key in ("ciphertext", "nonce", "wrap_meta", "created_at", "updated_at")):
                raise ValueError("incomplete field envelope")
            seen.add(name)
        return [dict(item) for item in raw]
    except (TypeError, ValueError, InvalidFieldNameError):
        # Neither malformed serialized values nor exception details are safe to log.
        _warn_corrupt_fields(str(row.get("name") or ""), str(row.get("id") or ""), str(row.get("updated_at") or ""))
        if strict:
            raise FieldsCorruptError(f"secret {row.get('name')!r} has corrupt fields; existing data was preserved") from None
        return []


def secret_field_names(row: dict[str, Any]) -> list[str]:
    return [_default_field_name(row), *[str(item["name"]) for item in _extra_field_rows(row, strict=False)]]


def record_name_for_field(secret_name: str, field_name: str, *, default_field: str = "value") -> str:
    return secret_name if field_name == default_field else f"{secret_name}.{field_name}"


def _record_entries(row: dict[str, Any], *, strict: bool = False) -> list[dict[str, Any]]:
    default_field = _default_field_name(row)
    entries = [
        {
            "name": row["name"],
            "field": default_field,
            "envelope": _row_sealed(row),
            "kind": row.get("kind"),
            "protection": row.get("protection"),
        }
    ]
    for field in _extra_field_rows(row, strict=strict):
        entries.append(
            {
                "name": record_name_for_field(str(row["name"]), str(field["name"]), default_field=default_field),
                "field": str(field["name"]),
                "envelope": Sealed(
                    ciphertext=field["ciphertext"], nonce=field["nonce"], wrap_meta=field["wrap_meta"]
                ),
                "kind": row.get("kind"),
                "protection": row.get("protection"),
            }
        )
    return entries


def _resolve_record_ref(conn: Connection, ref: str, *, user_context: Any = None) -> tuple[dict[str, Any], dict[str, Any]]:
    raw = str(ref or "").strip()
    parts = raw.split(".", 1)
    secret_name = parts[0]
    if not vault_crypto.is_valid_secret_name(secret_name):
        raise InvalidSecretNameError(secret_name)
    row = require_secret_access(conn, secret_name, user_context=user_context)
    field_ref = parts[1] if len(parts) == 2 else None
    default_field = _default_field_name(row)
    if field_ref is not None and row.get("kind") == "keypair":
        raise FieldsNotSupportedError(f"{secret_name} does not support fields")
    if field_ref is None or field_ref == default_field:
        field_name = default_field
    else:
        _validate_field_name(field_ref)
        if field_ref not in {str(item["name"]) for item in _extra_field_rows(row, strict=True)}:
            raise FieldNotFoundError(f"field {field_ref!r} not found on {secret_name}; fields: {', '.join(secret_field_names(row))}")
        field_name = field_ref
    entry = next(item for item in _record_entries(row) if item["field"] == field_name)
    return row, entry


def validate_field_name(value: Any, *, field: str = "field") -> str:
    return _validate_field_name(value, field=field)


def secret_record_names(secret: dict[str, Any]) -> list[str]:
    name = str(secret.get("name") or "")
    default_field = str(secret.get("default_field") or _default_field_name(secret))
    raw_fields = secret.get("fields")
    fields = raw_fields if isinstance(raw_fields, list) else [default_field]
    result = [name]
    for raw_field in fields:
        field = str(raw_field)
        if field != default_field:
            result.append(f"{name}.{field}")
    return result


def get_secret_record_meta(conn: Connection, ref: str, *, user_context: Any = None) -> dict[str, Any]:
    row, entry = _resolve_record_ref(conn, ref, user_context=user_context)
    payload = _meta_payload(row)
    payload["record_name"] = str(entry["name"])
    payload["field"] = str(entry["field"])
    return payload


def require_secret_management(conn: Connection, name: str, *, user_context: Any = None) -> dict[str, Any]:
    return _require_secret_resource_management(conn, _require_row(conn, name), resolve_resource_access_context(user_context))


def _reject_provision_spec_secret_fields(value: Any, *, path: str = "spec") -> None:
    if isinstance(value, dict):
        for key, item in value.items():
            if str(key) in PROVISION_SPEC_FORBIDDEN_KEYS:
                raise VaultServiceError(f"{path}.{key} is not allowed in vault request spec")
            _reject_provision_spec_secret_fields(item, path=f"{path}.{key}")
    elif isinstance(value, list):
        for index, item in enumerate(value):
            _reject_provision_spec_secret_fields(item, path=f"{path}[{index}]")


def _string_list(value: Any, *, field: str) -> list[str]:
    if value is None:
        return []
    if not isinstance(value, list):
        raise VaultServiceError(f"{field} must be an array of strings")
    out: list[str] = []
    for item in value:
        if not isinstance(item, str):
            raise VaultServiceError(f"{field} must be an array of strings")
        stripped = item.strip()
        if stripped:
            out.append(stripped)
    return out


def _normalize_tag(value: str, *, field: str = "tag") -> str:
    tag = value.strip()
    if not tag:
        raise VaultServiceError(f"{field} must be a non-empty string")
    if any(ch.isspace() for ch in tag):
        raise VaultServiceError(f"{field} must not contain whitespace")
    return tag


def skill_tag(skill: str) -> str:
    skill_name = _normalize_tag(skill, field="skill")
    if skill_name.startswith(SKILL_TAG_PREFIX):
        return skill_name
    return f"{SKILL_TAG_PREFIX}{skill_name}"


def _normalize_tags(tags: list[str] | None) -> list[str]:
    return list(dict.fromkeys(_normalize_tag(tag) for tag in (tags or []) if isinstance(tag, str) and tag.strip()))


def _row_tags(row: dict[str, Any]) -> list[str]:
    raw = _loads(row.get("tags")) or []
    if not isinstance(raw, list):
        return []
    return [str(tag) for tag in raw if isinstance(tag, str) and tag]


def _normalize_allowed_host(value: str, *, field: str) -> str:
    raw = value.strip().lower()
    if not raw:
        raise VaultServiceError(f"{field} must contain non-empty host strings")
    leading_dot = raw.startswith(".")
    hostish = raw[1:] if leading_dot else raw
    if "://" in hostish:
        host = urlsplit(hostish).hostname or ""
    elif hostish.startswith("[") or "/" in hostish or "?" in hostish or "#" in hostish or hostish.count(":") == 1:
        host = urlsplit(f"//{hostish}").hostname or ""
    else:
        host = hostish
    if not host or any(ch.isspace() for ch in host) or "/" in host or "*" in host:
        raise VaultServiceError(f"{field} entries must be hostnames, URLs, or host:port values")
    return f".{host}" if leading_dot else host


def _allowed_host_list(value: Any, *, field: str) -> list[str]:
    return list(dict.fromkeys(_normalize_allowed_host(item, field=field) for item in _string_list(value, field=field)))


def _optional_string(value: Any, *, field: str) -> str | None:
    if value is None:
        return None
    if not isinstance(value, str):
        raise VaultServiceError(f"{field} must be a string")
    stripped = value.strip()
    return stripped or None


def _validate_fetch_auth_name(auth_type: str, auth_name: str, *, field: str) -> None:
    if auth_type == "header":
        if auth_name.strip().lower() in FORBIDDEN_FETCH_AUTH_HEADER_NAMES:
            raise VaultServiceError(f"{field} cannot be {auth_name!r}")
        if not FETCH_AUTH_HEADER_NAME_RE.fullmatch(auth_name):
            raise VaultServiceError(f"{field} must be a valid HTTP header name")
    elif auth_type == "query" and not FETCH_AUTH_QUERY_NAME_RE.fullmatch(auth_name):
        raise VaultServiceError(f"{field} must be a valid query parameter name")


def _normalize_fetch_policy(policy: Any, *, field: str = "policy", allowed_extra_keys: set[str] | None = None) -> dict[str, Any]:
    if policy is None:
        return {}
    if not isinstance(policy, dict):
        raise VaultServiceError(f"{field} must be an object")
    extra_policy_keys = set(policy) - PROVISION_SPEC_ALLOWED_POLICY_KEYS - (allowed_extra_keys or set())
    if extra_policy_keys:
        raise VaultServiceError(f"unsupported {field} fields: {', '.join(sorted(extra_policy_keys))}")
    normalized_policy: dict[str, Any] = {}
    allowed_hosts = _allowed_host_list(policy.get("allowed_hosts"), field=f"{field}.allowed_hosts") if "allowed_hosts" in policy else []
    if allowed_hosts:
        normalized_policy["allowed_hosts"] = allowed_hosts
    auth = policy.get("auth")
    if auth is not None:
        if not isinstance(auth, dict):
            raise VaultServiceError(f"{field}.auth must be an object")
        extra_auth_keys = set(auth) - PROVISION_SPEC_ALLOWED_AUTH_KEYS
        if extra_auth_keys:
            raise VaultServiceError(f"unsupported {field}.auth fields: {', '.join(sorted(extra_auth_keys))}")
        raw_auth_type = auth.get("type") or "bearer"
        if not isinstance(raw_auth_type, str):
            raise VaultServiceError(f"{field}.auth.type must be a string")
        auth_type = raw_auth_type.strip().lower()
        if auth_type not in {"bearer", "header", "query"}:
            raise VaultServiceError(f"{field}.auth.type must be bearer, header, or query")
        normalized_auth: dict[str, Any] = {"type": auth_type}
        auth_name = _optional_string(auth.get("name"), field=f"{field}.auth.name") if "name" in auth else None
        if auth_type in {"header", "query"}:
            if not auth_name:
                raise VaultServiceError(f"{field}.auth.name is required for header/query auth")
            _validate_fetch_auth_name(auth_type, auth_name, field=f"{field}.auth.name")
            normalized_auth["name"] = auth_name
        elif auth_name:
            normalized_auth["name"] = auth_name
        normalized_policy["auth"] = normalized_auth
    return normalized_policy


def _stored_fetch_policy_visible_snapshot(policy: dict[str, Any]) -> dict[str, Any]:
    """Best-effort comparable view of persisted fetch policy.

    Older or hand-edited rows may contain auth names that the current write path
    rejects. Do not normalize the old value here; edits must still be able to
    replace an unsafe legacy policy with a valid one.
    """

    snapshot: dict[str, Any] = {}
    allowed_hosts = policy.get("allowed_hosts")
    if allowed_hosts:
        snapshot["allowed_hosts"] = allowed_hosts
    auth = policy.get("auth")
    if auth is not None:
        snapshot["auth"] = auth
    return snapshot


def normalize_provision_spec(spec: Any) -> dict[str, Any]:
    """Return non-secret creation hints for a provision request.

    The request spec is agent-provided metadata only. It can pre-fill the browser
    form and propose skill links, but it must never carry plaintext or sealed
    value material.
    """

    if spec is None:
        return {}
    if not isinstance(spec, dict):
        raise VaultServiceError("vault request spec must be a JSON object")
    _reject_provision_spec_secret_fields(spec)
    extra_keys = set(spec) - PROVISION_SPEC_ALLOWED_KEYS
    if extra_keys:
        raise VaultServiceError(f"unsupported vault request spec fields: {', '.join(sorted(extra_keys))}")

    normalized: dict[str, Any] = {}
    kind = spec.get("kind")
    if kind is not None:
        if not isinstance(kind, str):
            raise VaultServiceError("spec.kind must be a string")
        kind = kind.strip().lower()
        if kind != "static":
            raise VaultServiceError("spec.kind currently supports only 'static' for provision requests")
        normalized["kind"] = kind

    protection = spec.get("protection")
    if protection is not None:
        if not isinstance(protection, str):
            raise VaultServiceError("spec.protection must be a string")
        protection = protection.strip().lower()
        if protection not in {"standard", "protected"}:
            raise VaultServiceError("spec.protection must be 'standard' or 'protected'")
        normalized["protection"] = protection

    description = _optional_string(spec.get("description"), field="spec.description") if "description" in spec else None
    if description:
        normalized["description"] = description

    tags = _string_list(spec.get("tags"), field="spec.tags") if "tags" in spec else []
    tags = _normalize_tags(tags)

    if "fields" in spec:
        raw_fields = spec.get("fields")
        if not isinstance(raw_fields, list):
            raise VaultServiceError("spec.fields must be an array of field names")
        fields = [_validate_field_name(item, field="spec.fields") for item in raw_fields]
        if len(fields) != len(set(fields)):
            raise VaultServiceError("spec.fields must contain unique field names")
        if not fields:
            raise VaultServiceError("spec.fields must contain at least one field")
        if len(fields) > MAX_SECRET_FIELDS:
            raise TooManyFieldsError(f"a vault secret can have at most {MAX_SECRET_FIELDS} fields")
        normalized["fields"] = fields
        default_field = spec.get("default_field", fields[0])
        default_field = _validate_field_name(default_field, field="spec.default_field")
        if default_field not in fields:
            raise VaultServiceError("spec.default_field must be one of spec.fields")
        normalized["default_field"] = default_field
    elif "default_field" in spec:
        raise VaultServiceError("spec.default_field requires spec.fields")
    if "policy" in spec:
        normalized_policy = _normalize_fetch_policy(spec.get("policy"), field="spec.policy")
        if normalized_policy:
            normalized["policy"] = normalized_policy

    links = spec.get("links")
    if links is not None:
        if not isinstance(links, dict):
            raise VaultServiceError("spec.links must be an object")
        extra_link_keys = set(links) - {"skills"}
        if extra_link_keys:
            raise VaultServiceError(f"unsupported spec.links fields: {', '.join(sorted(extra_link_keys))}")
        skills = _string_list(links.get("skills"), field="spec.links.skills") if "skills" in links else []
        if skills:
            normalized_skills = list(dict.fromkeys(_normalize_tag(skill, field="spec.links.skills") for skill in skills))
            tags = list(dict.fromkeys([*tags, *(skill_tag(skill) for skill in normalized_skills)]))
            normalized["links"] = {"skills": normalized_skills}

    if tags:
        normalized["tags"] = tags

    return normalized


def _meta_payload(row: dict[str, Any]) -> dict[str, Any]:
    """Masked, value-free metadata for a secret row."""
    public_meta = _public_meta(row.get("public_meta"))
    kind = row.get("kind")
    protection = row.get("protection")
    payload = {
        **_field_metadata(row),
        "tags": _row_tags(row),
        "kind": kind,
        "protection": protection,
        "signer_kind": row.get("signer_kind"),
        "source": row.get("source"),
        "access_grantable": _secret_agent_access_grantable(row),
        "per_use_sign": _secret_agent_per_use_signable(row),
        "description": public_meta.get("description"),
        # Policy is non-secret (allowed hosts, auth scheme name) — safe to surface.
        "policy": _loads(row.get("policy")) or {},
        "last_used_at": row.get("last_used_at"),
        "use_count": row.get("use_count"),
        "created_at": row.get("created_at"),
        "updated_at": row.get("updated_at"),
    }
    pubkey_pin = public_meta.get("avault_pubkey_pin")
    if isinstance(pubkey_pin, dict):
        payload["avault_pubkey_pin"] = {
            key: value
            for key, value in pubkey_pin.items()
            if key in {"public_key", "fingerprint", "attested_at", "attestation"}
        }
    signing_public_key = public_meta.get("signing_public_key")
    if isinstance(signing_public_key, dict):
        # Surface derived receive addresses instead of the raw public key: agents and the
        # UI identify a signing key by address, not hex. Derivation is a pure function of the
        # (public) key; a malformed/legacy key degrades to no addresses, never a hard error.
        public_key = signing_public_key.get("public_key")
        if isinstance(public_key, str) and signing_public_key.get("curve") == "secp256k1":
            try:
                payload["signing_addresses"] = derive_addresses(public_key)
            except Exception:
                logger.warning("failed to derive signing addresses for secret %r", row.get("name"))
    return payload


def _row_sealed(row: dict[str, Any]) -> Sealed:
    return Sealed(ciphertext=row["ciphertext"], nonce=row["nonce"], wrap_meta=row["wrap_meta"])


def _protected_unlock_material(row: dict[str, Any]) -> dict[str, Any] | None:
    """Return the default record's opaque protected unlock material.

    This single-object shape is still used by signing and reveal cards. Grant
    options use ``_protected_unlock_material_records`` so every record is
    covered without changing this legacy surface.
    """
    if row.get("protection") != "protected":
        return None
    return {
        "name": str(row["name"]),
        "kind": row.get("kind"),
        "envelope": {
            "ciphertext": row["ciphertext"],
            "nonce": row["nonce"],
            "wrap_meta": row["wrap_meta"],
        },
    }


def _protected_unlock_material_records(row: dict[str, Any]) -> list[dict[str, Any]]:
    if row.get("protection") != "protected":
        return []
    materials: list[dict[str, Any]] = []
    for entry in _record_entries(row):
        envelope = entry["envelope"]
        materials.append(
            {
                "name": entry["name"],
                "field": entry["field"],
                "kind": row.get("kind"),
                "envelope": {
                    "ciphertext": envelope.ciphertext,
                    "nonce": envelope.nonce,
                    "wrap_meta": envelope.wrap_meta,
                },
            }
        )
    return materials


def _member_version(row: dict[str, Any]) -> dict[str, Any]:
    return {
        "name": row["name"],
        "secret_id": row.get("id"),
        "updated_at": row.get("updated_at"),
        "created_at": row.get("created_at"),
    }


def _member_version_matches(row: dict[str, Any], version: dict[str, Any]) -> bool:
    return (
        row.get("name") == version.get("name")
        and row.get("id") == version.get("secret_id")
        and row.get("updated_at") == version.get("updated_at")
    )


def _normalize_request_audience(audience: str | None) -> str:
    return audience if audience in REQUEST_AUDIENCES else REQUEST_AUDIENCE_UI


def _request_audience_from_requester(requester: Any) -> str:
    if not isinstance(requester, dict):
        return REQUEST_AUDIENCE_UI
    source = str(requester.get("source") or "").strip()
    if source in {"agent-cli", "cli"} or requester.get("backend") or requester.get("native_session_id"):
        return REQUEST_AUDIENCE_AGENT
    return REQUEST_AUDIENCE_UI


def _requester_with_authorization(requester: Any, context: Any) -> Any:
    """Record the authority a request was actually made under, in the requester JSON.

    A request outlives the call that created it: it is decided later, and its
    auto-resume turn is dispatched later still. The rest of the requester object
    is descriptive provenance the caller supplies, so a deferred consumer cannot
    trust it — the snapshot written here comes from the resolved context, and any
    copy the caller sent is dropped first by the same helper Runs and Harness
    definitions use.

    A local caller keeps the historical shape exactly: no key, and a request that
    had no requester at all still stores NULL.
    """

    from storage import resource_access_service

    if not isinstance(requester, dict):
        if not bool(getattr(context, "is_remote", False)):
            return requester
        requester = {}
    return resource_access_service.metadata_with_resource_user_context(requester, context)


def _require_request_session_authority(conn: Connection, session_id: Any, context: Any) -> None:
    """Hold a request to the session its approval would resume.

    A request is decided later, and deciding it resumes the session the
    requester named — so that session is an effect of the request, not a label
    on it. A requester who could not start a turn there has to be refused before
    the pending row exists; otherwise the refusal arrives only after a person
    has been asked to approve, and the request sits in their queue meanwhile.

    Only a session that exists is an effect. A request naming no session, or an
    id no session answers to, resumes nothing and stays as useful as it has
    always been — refusing those would be a new rule about request shape rather
    than about authority. Roles that manage the runtime already reach every
    session, so they are not asked.
    """

    identity = str(session_id or "").strip()
    if not identity or bool(getattr(context, "can_manage_instance", False)):
        return
    known = conn.execute(
        select(agent_sessions.c.id).where(agent_sessions.c.id == identity).limit(1)
    ).first()
    if known is None:
        return

    from core.vibe_agents import VibeAgentAccessError
    from storage.workbench_sessions_service import require_session_turn_authority
    from vibe.authorization import InstanceAuthorizationError

    try:
        require_session_turn_authority(conn, identity, authorization_context=context)
    except (LookupError, InstanceAuthorizationError, VibeAgentAccessError) as exc:
        raise VaultSecretAccessError("Vault request session access is not permitted.") from exc


def request_authorization_snapshot(row: dict[str, Any]) -> dict[str, Any] | None:
    """The trusted authority stored with a request, for its deferred consumers."""

    from storage.resource_access_service import RESOURCE_USER_CONTEXT_METADATA_KEY

    requester, _ = _request_json_payloads(row)
    if not isinstance(requester, dict):
        return None
    snapshot = requester.get(RESOURCE_USER_CONTEXT_METADATA_KEY)
    return dict(snapshot) if isinstance(snapshot, dict) else None


def _public_requester_payload(requester: Any) -> Any:
    """Strip the internal authority snapshot from an outward requester view."""

    from storage.resource_access_service import RESOURCE_USER_CONTEXT_METADATA_KEY

    if not isinstance(requester, dict):
        return requester
    if RESOURCE_USER_CONTEXT_METADATA_KEY not in requester:
        return requester
    # A copy: the row's own payload stays intact for the internal consumers that
    # read it after this projection has been handed out.
    public = dict(requester)
    public.pop(RESOURCE_USER_CONTEXT_METADATA_KEY, None)
    return public


def _card_hydration_policy(audience: str | None) -> CardHydrationPolicy:
    normalized = _normalize_request_audience(audience)
    return CardHydrationPolicy(
        audience=normalized,
        include_protected_unlock_material=normalized == REQUEST_AUDIENCE_UI,
    )


ACTIVE_GRANT_STATES = {"active", "reserved"}
ACTIVE_GRANT_STATUSES = ACTIVE_GRANT_STATES


def _grant_is_active(row: dict[str, Any]) -> bool:
    if row.get("status") not in ACTIVE_GRANT_STATES:
        return False
    expires_at = _parse_iso_datetime(row.get("expires_at"))
    return expires_at is None or expires_at > datetime.now(timezone.utc)


def grant_row_has_resident_agent_ready(row: dict[str, Any]) -> bool:
    if not _grant_is_active(row):
        return False
    try:
        return int(row.get("agent_ready") or 0) == 1
    except (TypeError, ValueError):
        return False


def _grant_members_are_standard_secrets(conn: Connection, members: list[str]) -> bool:
    if not members:
        return False
    rows = conn.execute(
        select(vault_secrets.c.name, vault_secrets.c.protection).where(vault_secrets.c.name.in_(members))
    ).mappings()
    protection_by_name = {str(item["name"]): item.get("protection") for item in rows}
    return set(protection_by_name) == set(members) and all(
        protection == "standard" for protection in protection_by_name.values()
    )


def _grant_readiness(
    conn: Connection,
    row: dict[str, Any],
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    members: list[str] | None = None,
) -> GrantReadiness:
    members = _grant_member_names(row) if members is None else members
    active = _grant_is_active(row)
    persisted_agent_ready = active and grant_row_has_resident_agent_ready(row)
    if persisted_agent_ready and members:
        cache.put(str(row["id"]), members, expires_at=row.get("expires_at"))
    runtime_members = cache.covered_names(str(row["id"])) if active else []
    runtime_agent_ready = persisted_agent_ready and bool(members) and set(members).issubset(set(runtime_members))
    standard_ready = active and _grant_members_are_standard_secrets(conn, members)
    delivery_ready = standard_ready or runtime_agent_ready
    delivery_status = (
        "standard_ready"
        if standard_ready
        else ("agent_cache_ready" if runtime_agent_ready else "agent_cache_unverified")
    )
    return GrantReadiness(
        active=active,
        persisted_agent_ready=persisted_agent_ready,
        runtime_agent_ready=runtime_agent_ready,
        standard_ready=standard_ready,
        delivery_ready=delivery_ready,
        delivery_status=delivery_status,
    )


def _grant_row_payload(
    conn: Connection,
    row: dict[str, Any],
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
) -> dict[str, Any]:
    members = _grant_member_names(row)
    readiness = _grant_readiness(conn, row, cache=cache, members=members)
    grant_id = row["id"]
    runtime_members = cache.covered_names(grant_id) if readiness.active else []
    return {
        "id": grant_id,
        "source_selector": _loads(row.get("source_selector")) or {},
        "session_id": row.get("session_id"),
        "purpose": row.get("purpose"),
        "status": row.get("status"),
        "request_id": row.get("request_id"),
        "created_at": row.get("created_at"),
        "expires_at": row.get("expires_at"),
        "revoked_at": row.get("revoked_at"),
        "member_snapshot": members,
        "member_count": len(members),
        "runtime_member_count": len(runtime_members),
        "delivery_ready": readiness.delivery_ready,
        "delivery_status": readiness.delivery_status,
        "one_shot": bool(int(row.get("one_shot") or 0)),
    }


def _clear_grant_agent_ready(conn: Connection, grant_id: str) -> None:
    conn.execute(
        vault_grants.update()
        .where(vault_grants.c.id == grant_id)
        .values(agent_ready=0, agent_ready_at=None)
    )


def _grant_member_names(row: dict[str, Any]) -> list[str]:
    members = _loads(row.get("member_snapshot")) or []
    if not isinstance(members, list):
        return []
    return [str(name) for name in members if isinstance(name, str) and name]


def _grant_payload(conn: Connection, row: dict[str, Any], *, cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE) -> dict[str, Any]:
    return _grant_row_payload(conn, dict(row), cache=cache)


def _unique_grant_release_refs(rows: list[dict[str, Any]]) -> list[dict[str, str]]:
    seen: set[str] = set()
    refs: list[dict[str, str]] = []
    for row in rows:
        key = str(row.get("id") or "")
        if not key:
            continue
        if key in seen:
            continue
        seen.add(key)
        refs.append({"grant_id": key})
    return refs


def _field_metadata(row: dict[str, Any]) -> dict[str, Any]:
    default_field = _default_field_name(row)
    payload = {"name": str(row["name"]), "kind": str(row.get("kind") or "static"), "default_field": default_field, "fields": [default_field]}
    try:
        payload["fields"].extend(item["name"] for item in _extra_field_rows(row, strict=True))
    except FieldsCorruptError:
        payload["fields_state"] = "corrupt"
    return payload


def _hydrate_card_delete_metadata(conn: Connection, row: dict[str, Any], card: dict[str, Any]) -> dict[str, Any]:
    card = dict(card)
    secret_name = row.get("secret_name")
    if not secret_name:
        return card
    secret_row = conn.execute(select(vault_secrets).where(vault_secrets.c.name == secret_name)).mappings().first()
    if secret_row is not None:
        card.pop("fields_state", None)
        card.update(_field_metadata(dict(secret_row)))
    return card


def _hydrate_card_unlock_material(conn: Connection, row: dict[str, Any], card: dict[str, Any]) -> dict[str, Any]:
    card = dict(card)
    secret_name = row.get("secret_name")
    if secret_name:
        secret_row = conn.execute(select(vault_secrets).where(vault_secrets.c.name == secret_name)).mappings().first()
        if secret_row is not None:
            material = _protected_unlock_material(dict(secret_row))
            if material is not None:
                card["secret_unlock_material"] = material
    hydrated_options: list[dict[str, Any]] = []
    for option in card.get("grant_options") or []:
        if not isinstance(option, dict):
            continue
        option_payload = dict(option)
        versions = option_payload.get("member_versions") or []
        materials: list[dict[str, Any]] = []
        if isinstance(versions, list):
            names = [item.get("name") for item in versions if isinstance(item, dict) and isinstance(item.get("name"), str)]
            current_rows = {
                current["name"]: dict(current)
                for current in conn.execute(select(vault_secrets).where(vault_secrets.c.name.in_(names))).mappings()
            }
            snapshots = {
                str(item["name"]): item for item in option_payload.get("member_fields") or []
                if isinstance(item, dict) and isinstance(item.get("name"), str)
            }
            # Labels are display metadata, not the frozen authorization member set.
            # In particular, a default rename deliberately preserves this request.
            option_payload["member_fields"] = [
                _field_metadata(current_rows[name]) if name in current_rows else snapshots[name]
                for name in option_payload.get("member_snapshot") or names
                if name in current_rows or name in snapshots
            ]
            for version in versions:
                if not isinstance(version, dict):
                    continue
                current = current_rows.get(version.get("name"))
                if current is None or not _member_version_matches(current, version):
                    continue
                materials.extend(_protected_unlock_material_records(current))
        if materials:
            option_payload["unlock_material"] = materials
        hydrated_options.append(option_payload)
    if hydrated_options:
        card["grant_options"] = hydrated_options
    return card


def _request_session_summary(conn: Connection, session_id: str | None) -> dict[str, Any] | None:
    """Resolve the request's originating session into UI-facing display metadata."""
    if not session_id:
        return None
    row = conn.execute(
        select(
            agent_sessions.c.id,
            agent_sessions.c.scope_id,
            agent_sessions.c.title,
            scopes.c.platform,
            scopes.c.scope_type,
            scopes.c.native_id,
            scopes.c.display_name,
        )
        .select_from(agent_sessions.join(scopes, scopes.c.id == agent_sessions.c.scope_id, isouter=True))
        .where(agent_sessions.c.id == session_id)
        .limit(1)
    ).mappings().first()
    if row is None:
        return {
            "id": session_id,
            "title": None,
            "label": session_id,
            "platform": None,
            "scope_kind": None,
            "is_workbench": False,
        }
    platform = str(row["platform"] or "").strip()
    scope_kind = str(row["scope_type"] or "").strip()
    is_workbench = row["scope_id"] is None or platform == "avibe" or scope_kind == "project"
    title = row["title"]
    label = title if is_workbench else (row["display_name"] or row["native_id"] or title or session_id)
    return {
        "id": row["id"],
        "title": title,
        "label": label,
        "platform": platform or None,
        "scope_kind": scope_kind or None,
        "is_workbench": is_workbench,
    }


def _request_row_payload(
    row: dict[str, Any],
    *,
    conn: Connection | None = None,
    audience: str | None = REQUEST_AUDIENCE_UI,
) -> dict[str, Any]:
    requester = _loads(row.get("requester"))
    delivery = _loads(row.get("delivery"))
    card = delivery.get("card") if isinstance(delivery, dict) else None
    policy = _card_hydration_policy(audience)
    if (
        conn is not None
        and isinstance(card, dict)
        and row.get("request_type") == "delete"
        and row.get("status") == "pending"
        and policy.audience == REQUEST_AUDIENCE_UI
    ):
        card = _hydrate_card_delete_metadata(conn, row, card)
    elif (
        policy.include_protected_unlock_material
        and row.get("status") == "pending"
        and row.get("request_type") != "delete"
        and conn is not None
        and isinstance(card, dict)
    ):
        card = _hydrate_card_unlock_material(conn, row, card)
    payload = {
        "id": row["id"],
        "request_type": row["request_type"],
        "secret_name": row.get("secret_name"),
        "requester": _public_requester_payload(requester),
        "delivery": delivery if isinstance(delivery, dict) else delivery,
        "status": row.get("status"),
        "message_id": row.get("message_id"),
        "created_at": row.get("created_at"),
        "decided_at": row.get("decided_at"),
        "expires_at": row.get("expires_at"),
        "card": card if isinstance(card, dict) else None,
    }
    if policy.audience == REQUEST_AUDIENCE_UI and conn is not None:
        payload["session"] = _request_session_summary(conn, _request_session_id(row))
    return payload


def _request_json_payloads(row: dict[str, Any]) -> tuple[Any, Any]:
    return _loads(row.get("requester")), _loads(row.get("delivery"))


def _request_waiter(delivery: Any) -> dict[str, Any]:
    if not isinstance(delivery, dict):
        return {}
    waiter = delivery.get("waiter")
    return waiter if isinstance(waiter, dict) else {}


# --- Approval continuation ownership ---------------------------------------------------------
#
# An approved request continues exactly one way: a synchronous CLI waiter consumes it in the
# command that asked, or the daemon resumes the requesting Session with a callback turn. Both
# sides decide inside a write-reserved transaction on the CURRENT row and land their decision
# with an update conditional on the ``delivery`` text they read, so neither can act on a
# decision the other has already made. A new waiter proves it is alive by holding an OS lock
# beside the database it waits in; the OS drops that lock when the process ends, however it
# ends. See docs/plans/2026-10-17-vault-continuation-ownership.md for the state shape.

#: ``waiter.liveness`` for a waiter whose owner holds its lock at ``request_waiter_lock_path``.
WAITER_LIVENESS_LOCK = "lock"
_WAITER_ID_PATTERN = re.compile(r"vw_[0-9a-f]{12}")


class ContinuationClaimedError(InvalidRequestError):
    """The request's continuation already belongs to someone else; the caller must not deliver."""


def new_request_waiter_id() -> str:
    return _id("vw")


def request_waiter_lock_path(db_path: str | Path, waiter_id: str) -> Path:
    """The waiter's ownership lock, beside the database whose request it waits on."""

    if not _WAITER_ID_PATTERN.fullmatch(str(waiter_id or "")):
        raise InvalidRequestError("invalid request waiter id")
    return Path(db_path).expanduser().resolve().parent / "vault-waiters" / f"{waiter_id}.lock"


def _database_file(connectable: Any) -> Path | None:
    database = connectable.engine.url.database
    if not database or database == ":memory:" or str(database).startswith("file:"):
        return None
    return Path(database)


def acquire_request_waiter_lock(engine: Any, waiter_id: str) -> MigrationFileLock:
    """Take a new waiter's ownership lock; raises ``OSError`` when it cannot be held."""

    db_path = _database_file(engine)
    if db_path is None:
        raise OSError("the vault database has no file to anchor a waiter lock beside")
    lock = MigrationFileLock(request_waiter_lock_path(db_path, waiter_id), timeout_seconds=0)
    lock.acquire()
    return lock


def release_request_waiter_lock(lock: MigrationFileLock, *, discard: bool) -> None:
    """Release a waiter's lock; ``discard`` once the waiter is terminal in the database.

    A waiter that leaves without a terminal commit must not discard: its row still says
    ``active``, and only a lock that can now be taken tells the daemon its owner is gone.
    """

    try:
        if discard:
            try:
                lock.lock_path.unlink()
            except OSError:
                pass
    finally:
        lock.release()


def discard_request_waiter_lock(connectable: Any, waiter_id: str) -> bool:
    """Remove a terminal waiter's lock file if no live process holds it."""

    db_path = _database_file(connectable)
    if db_path is None:
        return False
    try:
        path = request_waiter_lock_path(db_path, waiter_id)
    except InvalidRequestError:
        return False
    return remove_unheld_lock(path)


def _waiter_lock_state(conn: Connection | None, waiter: dict[str, Any]) -> LockHolderState:
    db_path = _database_file(conn) if conn is not None else None
    if db_path is None:
        return "unknown"
    try:
        path = request_waiter_lock_path(db_path, str(waiter.get("id") or ""))
    except InvalidRequestError:
        return "unknown"
    return probe_lock_holder(path)


def _waiter_presumed_live(conn: Connection | None, waiter: dict[str, Any]) -> bool:
    """Whether an armed waiter must still be treated as owning its request's continuation.

    A lock waiter is live while its lock is held and gone once the lock is free. A missing
    lock or a failed look proves nothing, so the waiter keeps its own declared wait bound.
    A waiter without ``liveness`` is a released row shape and keeps its recorded deadline.
    """

    if waiter.get("status") != "active":
        return False
    deadline = _parse_iso_datetime(waiter.get("deadline_at"))
    within_declared_wait = deadline is not None and deadline > datetime.now(timezone.utc)
    if waiter.get("liveness") != WAITER_LIVENESS_LOCK:
        return within_declared_wait
    state = _waiter_lock_state(conn, waiter)
    if state == "held":
        return True
    if state == "free":
        return False
    return within_declared_wait


def _request_waiter_live(conn: Connection | None, row: dict[str, Any]) -> bool:
    _, delivery = _request_json_payloads(row)
    return _waiter_presumed_live(conn, _request_waiter(delivery))


def _grant_owner_waiter_live(conn: Connection, grants: list[dict[str, Any]]) -> bool:
    request_ids = [
        str(grant.get("request_id") or "")
        for grant in grants
        if isinstance(grant, dict) and str(grant.get("request_id") or "")
    ]
    if not request_ids:
        return False
    rows = conn.execute(select(vault_requests).where(vault_requests.c.id.in_(request_ids))).mappings()
    return any(_request_waiter_live(conn, dict(row)) for row in rows)


def _request_continuation_claimed(delivery: dict[str, Any]) -> bool:
    continuation = delivery.get("continuation")
    return isinstance(continuation, dict) and continuation.get("owner") == "callback"


def _skip_sibling_callbacks_for_completed_waiter(conn: Connection, request_id: str) -> None:
    grant_rows = [
        dict(row)
        for row in conn.execute(select(vault_grants).where(vault_grants.c.request_id == request_id)).mappings()
    ]
    if not grant_rows:
        return
    sibling_ids: set[str] = set()
    for grant in grant_rows:
        session_id = str(grant.get("session_id") or "")
        purpose = str(grant.get("purpose") or "")
        member_set = {str(name) for name in (_loads(grant.get("member_snapshot")) or []) if str(name)}
        if not session_id or not purpose or not member_set:
            continue
        rows = conn.execute(
            select(vault_requests).where(
                vault_requests.c.id != request_id,
                vault_requests.c.request_type == "access",
                vault_requests.c.status == "approved",
                vault_requests.c.callback_status == "pending",
            )
        ).mappings()
        for row in rows:
            row_dict = dict(row)
            _, sibling_delivery = _request_json_payloads(row_dict)
            if isinstance(sibling_delivery, dict) and _request_continuation_claimed(sibling_delivery):
                # Its callback already owns its continuation; skipping now would drop that turn.
                continue
            try:
                option = _request_grant_option(row_dict)
            except InvalidRequestError:
                continue
            if (
                _request_session_id(row_dict) == session_id
                and option.purpose == purpose
                and _request_members_are_subset(row_dict, member_set)
            ):
                sibling_ids.add(str(row_dict["id"]))
    if sibling_ids:
        conn.execute(
            vault_requests.update()
            .where(vault_requests.c.id.in_(sorted(sibling_ids)), vault_requests.c.callback_status == "pending")
            .values(callback_status="skipped")
        )


def _reserve_request_row(conn: Connection, request_id: str) -> tuple[dict[str, Any], dict[str, Any]]:
    """Take SQLite's write lock, then read the request this transaction will decide on."""

    from storage.agent_session_rows import reserve_write_lock

    reserve_write_lock(conn)
    row = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().first()
    if row is None:
        raise RequestNotFoundError(request_id)
    row_dict = dict(row)
    _, delivery = _request_json_payloads(row_dict)
    return row_dict, dict(delivery) if isinstance(delivery, dict) else {}


def _land_request_delivery(conn: Connection, row: dict[str, Any], delivery: dict[str, Any], *conditions: Any) -> bool:
    """Write ``delivery`` only over the text this decision read; True when it landed."""

    read = row.get("delivery")
    unchanged = vault_requests.c.delivery.is_(None) if read is None else vault_requests.c.delivery == read
    result = conn.execute(
        vault_requests.update()
        .where(vault_requests.c.id == row["id"], unchanged, *conditions)
        .values(delivery=json.dumps(delivery))
    )
    return result.rowcount == 1


def _callback_not_sent() -> Any:
    # A released daemon records a delivered callback only as ``sent``; never continue past it.
    return or_(vault_requests.c.callback_status.is_(None), vault_requests.c.callback_status != "sent")


def _transition_own_waiter(
    conn: Connection,
    request_id: str,
    *,
    waiter_id: str,
    status: str,
    stamp: str,
    exclusive: bool,
) -> dict[str, Any]:
    row, delivery = _reserve_request_row(conn, request_id)
    current = _request_waiter(delivery)
    if current.get("id") != waiter_id:
        raise InvalidRequestError("request waiter id does not match")
    if current.get("status") != "active" or (
        exclusive and (_request_continuation_claimed(delivery) or row.get("callback_status") == "sent")
    ):
        raise ContinuationClaimedError(f"vault request {request_id} continues through its callback")
    now = _now()
    delivery["waiter"] = {**current, "status": status, "updated_at": now, stamp: now}
    conditions = (_callback_not_sent(),) if exclusive else ()
    if not _land_request_delivery(conn, row, delivery, *conditions):
        raise ContinuationClaimedError(f"vault request {request_id} continues through its callback")
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(updated), conn=conn, audience=REQUEST_AUDIENCE_AGENT)


def arm_request_waiter(
    conn: Connection,
    request_id: str,
    *,
    waiter_id: str,
    deadline_at: str,
    liveness: str | None = None,
) -> dict[str, Any]:
    """Make a synchronous CLI waiter the request's continuation owner.

    Raises ``ContinuationClaimedError`` once the callback owns the request (the caller must
    not wait or deliver) and ``InvalidRequestError`` when the request already has a waiter.
    """

    row, delivery = _reserve_request_row(conn, request_id)
    if _request_waiter(delivery):
        raise InvalidRequestError("request waiter id does not match")
    if _request_continuation_claimed(delivery) or row.get("callback_status") == "sent":
        raise ContinuationClaimedError(f"vault request {request_id} continues through its callback")
    waiter = {"id": waiter_id, "status": "active", "deadline_at": deadline_at, "updated_at": _now()}
    if liveness:
        waiter["liveness"] = liveness
    delivery["waiter"] = waiter
    if not _land_request_delivery(conn, row, delivery, _callback_not_sent()):
        raise ContinuationClaimedError(f"vault request {request_id} continues through its callback")
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(updated), conn=conn, audience=REQUEST_AUDIENCE_AGENT)


def complete_request_waiter(conn: Connection, request_id: str, *, waiter_id: str) -> dict[str, Any]:
    """Consume the request's outcome in the waiting command; only then may it deliver."""

    payload = _transition_own_waiter(
        conn, request_id, waiter_id=waiter_id, status="completed", stamp="completed_at", exclusive=True
    )
    _skip_sibling_callbacks_for_completed_waiter(conn, request_id)
    return payload


def timeout_request_waiter(conn: Connection, request_id: str, *, waiter_id: str) -> dict[str, Any]:
    """Hand an unconsumed request back to its callback when the waiter stops waiting."""

    return _transition_own_waiter(
        conn, request_id, waiter_id=waiter_id, status="timed_out", stamp="timed_out_at", exclusive=False
    )


def _request_session_id(row: dict[str, Any]) -> str | None:
    requester, delivery = _request_json_payloads(row)
    for payload in (requester, delivery):
        if isinstance(payload, dict) and payload.get("session_id"):
            return str(payload["session_id"])
    card = delivery.get("card") if isinstance(delivery, dict) else None
    if isinstance(card, dict) and card.get("session_id"):
        return str(card["session_id"])
    return None


def _expire_pending_request_rows(
    conn: Connection,
    rows: list[dict[str, Any]],
    *,
    reason: str = "request-expired",
    delivery_extra: dict[str, Any] | None = None,
) -> int:
    now = _now()
    expired = 0
    for row in rows:
        result = conn.execute(
            vault_requests.update()
            .where(vault_requests.c.id == row["id"], vault_requests.c.status == "pending")
            .values(status="expired", decided_at=now, callback_status="pending")
        )
        if result.rowcount != 1:
            continue
        delivery = {"request_type": row.get("request_type")}
        if delivery_extra:
            delivery.update(delivery_extra)
        audit(
            conn,
            reason,
            secret_name=row.get("secret_name"),
            delivery=delivery,
            request_id=row["id"],
        )
        expired += 1
    return expired


def _expire_request_if_due(conn: Connection, row: dict[str, Any]) -> tuple[dict[str, Any], bool]:
    expires_at = _parse_iso_datetime(row.get("expires_at"))
    if row.get("status") != "pending" or expires_at is None or expires_at > datetime.now(timezone.utc):
        return row, False
    expired = _expire_pending_request_rows(conn, [row])
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == row["id"])).mappings().one()
    return dict(updated), expired == 1


def _load_request_row(conn: Connection, request_id: str) -> dict[str, Any]:
    row = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().first()
    if row is None:
        raise RequestNotFoundError(request_id)
    row_dict, _ = _expire_request_if_due(conn, dict(row))
    return row_dict


def _load_request_for_transition(
    conn: Connection,
    request_id: str,
    *,
    request_type: str | None,
    allowed_statuses: set[str],
    wrong_type_message: str,
    wrong_status_message: str,
    expired_message: str,
) -> dict[str, Any]:
    row = _load_request_row(conn, request_id)
    if request_type is not None and row.get("request_type") != request_type:
        raise InvalidRequestError(wrong_type_message)
    if row.get("status") == "expired":
        raise InvalidRequestError(expired_message)
    if row.get("status") not in allowed_statuses:
        raise InvalidRequestError(wrong_status_message)
    return row


def _expire_pending_requests(conn: Connection) -> None:
    for row in conn.execute(select(vault_requests).where(vault_requests.c.status == "pending")).mappings():
        _expire_request_if_due(conn, dict(row))


def _payload_session_id(payload: Any) -> str | None:
    if isinstance(payload, dict) and payload.get("session_id"):
        return str(payload["session_id"])
    return None


# --- Auto-resume callbacks (P4) -------------------------------------------------------------
#
# When a request reaches a terminal state its transition also sets ``callback_status="pending"``.
# The daemon sweep (``core.scheduled_tasks``) drains these: ``claim_request_callback`` decides on
# the current row whether a synchronous waiter or the callback owns the continuation, the sweep
# enqueues one callback turn to the requesting session — the same entry Agent Run / watch /
# scheduled tasks use — or mirrors a waiter-consumed outcome, then marks the row ``sent`` /
# ``skipped``. The atomic ``WHERE status='pending'`` claim on every transition keeps a re-resolve
# from re-arming ``callback_status``.


@dataclass(frozen=True)
class PendingRequestCallback:
    """A resolved request's auto-resume plan: wake ``session_id`` with ``message``."""

    request_id: str
    session_id: str
    message: str


def _request_callback_disabled(row: dict[str, Any]) -> bool:
    requester, _ = _request_json_payloads(row)
    return bool(isinstance(requester, dict) and requester.get("callback_disabled"))


def has_named_field_shape(metadata: dict[str, Any]) -> bool:
    """Whether provision guidance needs a field-aware hint instead of legacy NAME."""
    if str(metadata.get("kind") or "static") == "keypair":
        return False
    default_field = str(metadata.get("default_field") or "value")
    fields = list(metadata.get("fields") or [default_field])
    return metadata.get("fields_state") == "corrupt" or fields != ["value"] or default_field != "value"


def provision_field_hint(metadata: dict[str, Any]) -> str:
    """Value-free current-field usage shared by synchronous and async provision replies."""
    name = str(metadata["name"])
    fields = list(metadata.get("fields") or [metadata.get("default_field") or "value"])
    default_field = str(metadata.get("default_field") or fields[0])
    labels = ", ".join(str(field) for field in fields)
    usage = (
        f" Current fields: {labels}. Default alias: `{name}.{default_field}`."
        f" Select a field with `vibe vault run --env {name}.{fields[-1]} -- <command>`."
    )
    if metadata.get("fields_state") == "corrupt":
        return usage + " Extra fields are unavailable because their stored metadata is corrupt."
    return usage + " Tag and skill selectors deliver every field."


def _build_request_callback_message(row: dict[str, Any]) -> str:
    """Agent-facing text delivered to the requesting session when a request resolves."""
    request_type = str(row.get("request_type") or "")
    status = str(row.get("status") or "")
    request_id = str(row.get("id") or "").strip()
    name = str(row.get("secret_name") or "").strip()
    label = f" '{name}'" if name else ""
    subject = {
        "provision": f"vault request for the secret{label}",
        "access": f"vault access request{label}",
        "sign": f"signature request{label}",
        "delete": f"vault delete request{label}",
    }.get(request_type, f"vault request{label}")

    if status in {"approved", "fulfilled"}:
        if request_type == "delete":
            return f"The user approved deleting the secret{label}; it has been deleted. Continue the task."
        if request_type == "provision":
            usage = f" You can use it, e.g. `vibe vault run --env {name} -- <command>`." if name else ""
            current = row.get("provision_secret")
            if name and isinstance(current, dict) and has_named_field_shape(current):
                usage = provision_field_hint(current)
            return f"The user provided your {subject}; the secret is now available.{usage} Continue the task."
        if request_type == "access":
            return f"The user approved your {subject}; the grant is ready. Continue the task."
        if request_type == "sign":
            # The public signature is the deliverable — the agent needs it to continue. It's stored
            # in the request; retrieving it by id returns immediately (the request is already done).
            retrieve = f" Retrieve the signature result with: vibe vault await {request_id}." if request_id else ""
            return (
                f"The user approved and completed your {subject}.{retrieve} "
                "Do not rerun `vibe vault sign`; use the returned signature and continue the task."
            )
        return f"The user approved your {subject}. Continue the task."
    if status == "denied":
        if request_type == "delete":
            return f"The user declined deleting the secret{label}. Do not retry — keep the secret and ask the user if needed."
        return f"The user declined your {subject}. Do not retry — adjust your approach or ask the user how to proceed."
    if status == "failed":
        # 'failed' is a signing error (transient/crypto/browser), NOT a user decision — retry is fine.
        return f"Your {subject} could not be completed due to a signing error (not a user decision). You may retry if it still makes sense."
    if status == "expired":
        return f"Your {subject} expired without a decision. Re-request it if you still need it, or continue without."
    return ""


def resolve_request_callback(row: dict[str, Any]) -> PendingRequestCallback | None:
    """Plan the auto-resume callback for a resolved request, or ``None`` to skip.

    Skipped when the requester opted out (``--no-callback``), the request has no originating
    session, or the terminal state maps to no message.
    """
    request_id = str(row.get("id") or "").strip()
    if not request_id or _request_callback_disabled(row):
        return None
    session_id = _request_session_id(row)
    if not session_id:
        return None
    message = _build_request_callback_message(row)
    if not message.strip():
        return None
    return PendingRequestCallback(request_id=request_id, session_id=session_id, message=message)


def _request_covering_grant_payloads(
    conn: Connection,
    row: dict[str, Any],
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
) -> list[dict[str, Any]]:
    request_members = set(_request_member_names(row))
    session_id = _request_session_id(row)
    if not request_members or not session_id:
        return []
    try:
        purpose = _request_grant_option(row).purpose
    except InvalidRequestError:
        return []

    expire_grants(conn, cache=cache)
    rows = conn.execute(
        select(vault_grants)
        .where(
            vault_grants.c.status.in_(ACTIVE_GRANT_STATES),
            vault_grants.c.session_id == session_id,
            vault_grants.c.purpose == purpose,
        )
        .order_by(vault_grants.c.created_at.desc(), vault_grants.c.id.desc())
    ).mappings()
    grants: list[dict[str, Any]] = []
    for grant_row in rows:
        grant = dict(grant_row)
        grant_members = {str(name) for name in (_loads(grant.get("member_snapshot")) or []) if str(name)}
        if request_members.issubset(grant_members):
            grants.append(_grant_payload(conn, grant, cache=cache))
    return grants


def request_callback_ready(conn: Connection, row: dict[str, Any]) -> bool:
    """Whether a resolved request's callback may be delivered yet (vs. deferred to a later sweep).

    An approved *access* request is only usable once a covering grant is delivery-ready: for a
    protected secret the DEKs are relayed to the resident agent AFTER approval, so resuming the
    agent before then would hand it a grant whose ``delivery_ready`` is still false. Sibling access
    requests approved by the same grant do not own ``vault_grants.request_id``, so readiness follows
    the active grant for the request's session/purpose whose member snapshot covers the request's
    members. Every other terminal state (provision/sign/deny/expire, and standard grants which are
    ready on approval) is deliverable immediately; no active covering grant does not block forever.
    A live synchronous waiter, on this request or on the covering grant's request, also defers it.
    """
    if _request_waiter_live(conn, row):
        return False
    if str(row.get("request_type") or "") == "access" and str(row.get("status") or "") == "approved":
        grants = _request_covering_grant_payloads(conn, row)
        if grants and _grant_owner_waiter_live(conn, grants):
            return False
        if grants and not any(grant.get("delivery_ready") for grant in grants):
            return False
    return True


def request_callback_consumed_by_waiter(row: dict[str, Any]) -> bool:
    """Whether the terminal result already returned through a synchronous CLI waiter."""

    _, delivery = _request_json_payloads(row)
    return str(_request_waiter(delivery).get("status") or "") == "completed"


def expire_overdue_requests(conn: Connection) -> None:
    """Flip any overdue pending requests to ``expired`` (arming their callback) proactively.

    Expiry is otherwise lazy (only on request reads), so an unattended timed-out request would
    never auto-resume its session until some unrelated read happened to touch it. The callback
    sweep calls this first so overdue requests are expired and picked up in the same pass.
    """
    _expire_pending_requests(conn)


def earliest_pending_request_expiry(conn: Connection) -> datetime | None:
    """Return the next durable request-expiry deadline, if one exists."""

    expires_at = conn.execute(
        select(vault_requests.c.expires_at)
        .where(
            vault_requests.c.status == "pending",
            vault_requests.c.expires_at.is_not(None),
        )
        .order_by(vault_requests.c.expires_at)
        .limit(1)
    ).scalar_one_or_none()
    return _parse_iso_datetime(str(expires_at) if expires_at is not None else None)


def list_pending_request_callbacks(
    conn: Connection,
    *,
    limit: int | None = None,
    after: tuple[str, str] | None = None,
) -> list[dict[str, Any]]:
    """Terminal requests owed an auto-resume callback (``callback_status='pending'``)."""
    query = (
        select(vault_requests)
        .where(vault_requests.c.callback_status == "pending")
    )
    if after is not None:
        query = query.where(
            tuple_(vault_requests.c.decided_at, vault_requests.c.id)
            > tuple_(str(after[0]), str(after[1]))
        )
    query = query.order_by(vault_requests.c.decided_at, vault_requests.c.id)
    if limit is not None:
        query = query.limit(limit)
    rows = [dict(row) for row in conn.execute(query).mappings()]
    for row in rows:
        _attach_provision_projection(conn, row)
    return rows


def _attach_provision_projection(conn: Connection, row: dict[str, Any]) -> None:
    if row.get("request_type") != "provision" or row.get("status") != "fulfilled":
        return
    # Transient callback projection: use the user's actual current fields,
    # never the requested hints and never any envelope/value material.
    secret = conn.execute(
        select(vault_secrets.c.name, vault_secrets.c.kind, vault_secrets.c.id,
               vault_secrets.c.public_meta, vault_secrets.c.fields, vault_secrets.c.updated_at)
        .where(vault_secrets.c.name == row.get("secret_name"))
    ).mappings().first()
    if secret is not None:
        current = _field_metadata(dict(secret))
        if has_named_field_shape(current):
            row["provision_secret"] = current


@dataclass(frozen=True)
class RequestCallbackClaim:
    """What one callback pass may do for a request, decided on its current row.

    ``defer`` leaves it for a later pass, ``settled`` means it needs nothing more, ``mirror``
    records a waiter-consumed outcome in the transcript, and ``deliver`` enqueues the callback
    Run ``run_id``. ``released_waiter_id`` names a dead owner's lock that is now safe to remove.
    """

    action: str
    row: dict[str, Any] | None = None
    plan: PendingRequestCallback | None = None
    run_id: str | None = None
    released_waiter_id: str | None = None


def claim_request_callback(conn: Connection, request_id: str) -> RequestCallbackClaim:
    """Decide, on the current row, whether the Session callback owns this request's continuation.

    The callback claims the request before anything is enqueued, recording the Run id it will
    use, so a waiter arriving later is refused and a pass interrupted between enqueue and the
    ``sent`` mark resumes with the same Run instead of choosing again.
    """

    try:
        row, delivery = _reserve_request_row(conn, request_id)
    except RequestNotFoundError:
        return RequestCallbackClaim("settled")
    if row.get("callback_status") != "pending":
        return RequestCallbackClaim("settled", row)
    _attach_provision_projection(conn, row)
    plan = resolve_request_callback(row)
    if plan is None:
        mark_request_callback(conn, request_id, status="skipped")
        return RequestCallbackClaim("settled", row)
    if _request_continuation_claimed(delivery):
        run_id = str(delivery["continuation"].get("run_id") or "") or None
        return RequestCallbackClaim("deliver", row, plan, run_id=run_id)
    if request_callback_consumed_by_waiter(row):
        return RequestCallbackClaim("mirror", row, plan)
    if not request_callback_ready(conn, row):
        return RequestCallbackClaim("defer", row)
    waiter = _request_waiter(delivery)
    waiter_armed = waiter.get("status") == "active"
    now = _now()
    if waiter_armed:
        # Gone, or past its declared wait with no proof either way: abandoning it in this same
        # write is what refuses that waiter's completion.
        delivery["waiter"] = {**waiter, "status": "abandoned", "updated_at": now, "abandoned_at": now}
    run_id = uuid.uuid4().hex[:12]
    delivery["continuation"] = {"owner": "callback", "run_id": run_id, "claimed_at": now}
    if not _land_request_delivery(conn, row, delivery, vault_requests.c.callback_status == "pending"):
        return RequestCallbackClaim("defer", row)
    released = str(waiter.get("id") or "") if waiter_armed and waiter.get("liveness") == WAITER_LIVENESS_LOCK else None
    return RequestCallbackClaim("deliver", row, plan, run_id=run_id, released_waiter_id=released or None)


def mark_request_callback(conn: Connection, request_id: str, *, status: str) -> bool:
    """Record the outcome of an owed auto-resume callback (``sent`` / ``skipped`` / ``failed``).

    Only a still-pending callback is marked, so a skip decided elsewhere is never overwritten.
    """
    result = conn.execute(
        vault_requests.update()
        .where(vault_requests.c.id == request_id, vault_requests.c.callback_status == "pending")
        .values(callback_status=status)
    )
    return result.rowcount == 1


def _request_card(row: dict[str, Any]) -> dict[str, Any]:
    _, delivery = _request_json_payloads(row)
    card = delivery.get("card") if isinstance(delivery, dict) else None
    return card if isinstance(card, dict) else {}


def _request_member_names(row: dict[str, Any]) -> list[str]:
    card = _request_card(row)
    members: list[str] = []
    options = card.get("grant_options") if isinstance(card, dict) else None
    if isinstance(options, list):
        for option in options:
            if not isinstance(option, dict):
                continue
            snapshot = option.get("member_snapshot")
            if isinstance(snapshot, list):
                members.extend(str(name) for name in snapshot if isinstance(name, str) and name)
    if not members and row.get("secret_name"):
        members.append(str(row["secret_name"]))
    return sorted(set(members))


def _require_request_secret_access(
    conn: Connection,
    row: dict[str, Any],
    *,
    user_context: Any = None,
    management: bool = False,
) -> None:
    """Authorize a request before hydrating or mutating its member secrets."""

    context = resolve_resource_access_context(user_context)
    if context.has_role("editor"):
        return
    member_names = _request_member_names(row)
    if not member_names:
        raise VaultSecretAccessError("Vault secret access is not permitted.")
    secret_rows = {
        str(secret_row["name"]): dict(secret_row)
        for secret_row in conn.execute(select(vault_secrets).where(vault_secrets.c.name.in_(member_names))).mappings()
    }
    if set(secret_rows) != set(member_names):
        # Provision requests legitimately precede the secret. Only the paired
        # instance owner may inspect or decide those owner-level requests.
        if (
            context.is_instance_owner
            and row.get("request_type") == "provision"
        ):
            return
        raise VaultSecretAccessError("Vault secret access is not permitted.")
    require = _require_secret_resource_management if management else _require_secret_resource_access
    for name in member_names:
        require(conn, secret_rows[name], context)


def _request_covers_any_member(row: dict[str, Any], members: set[str]) -> bool:
    if not members:
        return False
    return bool(set(_request_member_names(row)) & members)


def _request_members_are_subset(row: dict[str, Any], members: set[str]) -> bool:
    request_members = set(_request_member_names(row))
    return bool(request_members) and request_members.issubset(members)


def _ttl_cap_from_grant_option(option: dict[str, Any], selector: dict[str, Any]) -> int:
    raw_options = option.get("ttl_options_seconds")
    ttl_options: list[int] = []
    if isinstance(raw_options, list):
        for raw in raw_options:
            try:
                value = int(raw)
            except (TypeError, ValueError):
                continue
            if value > 0:
                ttl_options.append(value)
    if ttl_options:
        return max(ttl_options)
    return max(GRANT_TTL_OPTIONS_SECONDS)


def _request_grant_option(row: dict[str, Any]) -> RequestGrantOption:
    card = _request_card(row)
    options = card.get("grant_options") if isinstance(card, dict) else None
    if not isinstance(options, list) or len(options) != 1 or not isinstance(options[0], dict):
        raise InvalidRequestError("grant approval request is missing a grant option")
    option = options[0]
    grant_id = str(option.get("grant_id") or "").strip()
    if not grant_id:
        raise InvalidRequestError("grant approval request is missing a grant id")
    snapshot = option.get("member_snapshot")
    if not isinstance(snapshot, list):
        raise InvalidRequestError("grant approval request has an invalid member snapshot")
    members = [str(name) for name in snapshot if isinstance(name, str) and name]
    selector = _source_selector_payload(option.get("source_selector") if isinstance(option.get("source_selector"), dict) else {})
    purpose = str(option.get("purpose") or "run")
    if purpose not in GRANT_PURPOSES:
        raise InvalidRequestError("grant approval request has an invalid purpose")
    return RequestGrantOption(
        grant_id=grant_id,
        members=members,
        source_selector=selector,
        purpose=purpose,
        one_shot=bool(option.get("one_shot")),
        ttl_cap_seconds=_ttl_cap_from_grant_option(option, selector),
    )


def _secret_policy(row: dict[str, Any]) -> dict[str, Any]:
    return _loads(row.get("policy")) or {}


def _secret_always_ask(row: dict[str, Any]) -> bool:
    return bool(_secret_policy(row).get("always_ask"))


def _secret_access_requestable(row: dict[str, Any]) -> bool:
    return row.get("kind") != "keypair"


def _secret_access_grantable(row: dict[str, Any]) -> bool:
    if row.get("kind") == "keypair":
        return False
    if _secret_always_ask(row):
        return False
    return True


def _secret_agent_access_grantable(row: dict[str, Any]) -> bool:
    return _secret_access_grantable(row)


def _secret_agent_per_use_signable(row: dict[str, Any]) -> bool:
    if row.get("kind") != "keypair" or row.get("signer_kind") not in (None, "local"):
        return False
    if row.get("protection") != "protected":
        return True
    signing_public_key = _public_meta(row.get("public_meta")).get("signing_public_key")
    return (
        isinstance(signing_public_key, dict)
        and signing_public_key.get("curve") == "secp256k1"
        and isinstance(signing_public_key.get("public_key"), str)
        and bool(signing_public_key.get("public_key"))
    )


def sign_headless_allowed(row: dict[str, Any]) -> bool:
    """A standard local keypair with no ``always_ask`` policy signs per-use without approval.

    Mirrors the standard *access* headless fast path (``protection == "standard"`` and not
    always_ask). Protected keys always sign in the browser under approval; a standard key
    whose policy sets ``always_ask`` is opted back into per-use approval (the reserved toggle).
    """
    if row.get("kind") != "keypair" or (row.get("signer_kind") or "local") != "local":
        return False
    if row.get("protection") != "standard":
        return False
    return not _secret_always_ask(row)


def sign_needs_approval(conn: Connection, name: str, *, user_context: Any = None) -> bool:
    """True when `vibe vault sign` must create a pending approval request for `name`."""
    return not sign_headless_allowed(require_secret_access(conn, name, user_context=user_context))


def _reject_unsignable_keypair(row: dict[str, Any], name: str) -> None:
    if not _secret_agent_per_use_signable(row):
        raise InvalidRequestError(f"{name} is not per-use signable")


def _reject_keypair_value_delivery(row: dict[str, Any], name: str) -> None:
    if row.get("kind") == "keypair":
        raise KeypairNotValueDeliverableError(f"{name} is a signing key; use vault_sign instead of value delivery")


def _audit_reference_secret_names(
    conn: Connection,
    *,
    secret_name: str | None,
    request_id: str | None,
    grant_id: str | None,
) -> list[str]:
    names = {str(secret_name)} if secret_name else set()
    if request_id:
        request_row = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().first()
        if request_row is not None:
            names.update(_request_member_names(dict(request_row)))
    if grant_id:
        grant_row = conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().first()
        if grant_row is not None:
            names.update(_grant_member_names(dict(grant_row)))
    return sorted(name for name in names if name)


def _build_audit_access_snapshot(conn: Connection, names: list[str]) -> dict[str, Any] | None:
    from storage import resource_access_service

    normalized_names = sorted({str(name) for name in names if str(name)})
    if not normalized_names:
        return None
    secret_rows = {
        str(row["name"]): dict(row)
        for row in conn.execute(select(vault_secrets).where(vault_secrets.c.name.in_(normalized_names))).mappings()
    }
    resources: list[dict[str, Any]] = []
    for name in normalized_names:
        secret_row = secret_rows.get(name)
        if secret_row is None:
            continue
        resource_id = str(secret_row.get("id") or "")
        if not resource_id:
            continue
        resources.append(
            {
                "name": name,
                "resource_id": resource_id,
                "policy": resource_access_service.get_resource_policy(
                    "vault_secret",
                    resource_id,
                    connection=conn,
                ),
            }
        )
    return {"version": 1, "resources": resources} if resources else None


def _audit_public_row(row: dict[str, Any]) -> dict[str, Any]:
    payload = dict(row)
    delivery = _loads(payload.get("delivery"))
    if isinstance(delivery, dict) and _AUDIT_ACCESS_SNAPSHOT_KEY in delivery:
        delivery.pop(_AUDIT_ACCESS_SNAPSHOT_KEY, None)
        payload["delivery"] = json.dumps(delivery) if delivery else None
    return payload


def audit(
    conn: Connection,
    event: str,
    *,
    secret_name: str | None = None,
    requester: Any = None,
    delivery: Any = None,
    request_id: str | None = None,
    grant_id: str | None = None,
    access_snapshot: dict[str, Any] | None = None,
) -> None:
    """Append one audit row. Callers pass only non-secret summaries."""
    snapshot = access_snapshot or _build_audit_access_snapshot(
        conn,
        _audit_reference_secret_names(
            conn,
            secret_name=secret_name,
            request_id=request_id,
            grant_id=grant_id,
        ),
    )
    stored_delivery = delivery
    if snapshot is not None and (delivery is None or isinstance(delivery, dict)):
        stored_delivery = dict(delivery or {})
        stored_delivery[_AUDIT_ACCESS_SNAPSHOT_KEY] = snapshot
    # The audit trail is a non-secret summary, and callers now hand it the same
    # requester payload the request row stores. That payload may carry the
    # internal authorization snapshot, which belongs to the request's deferred
    # consumers rather than to a log surface, so it is dropped here once for
    # every event instead of at each call site.
    stored_requester = _public_requester_payload(requester)
    conn.execute(
        vault_audit.insert().values(
            id=_id("vau"),
            ts=_now(),
            event=event,
            secret_name=secret_name,
            requester=json.dumps(stored_requester) if stored_requester is not None else None,
            delivery=json.dumps(stored_delivery) if stored_delivery is not None else None,
            request_id=request_id,
            grant_id=grant_id,
        )
    )


def _require_row(conn: Connection, name: str) -> dict[str, Any]:
    row = conn.execute(select(vault_secrets).where(vault_secrets.c.name == name)).mappings().first()
    if row is None:
        raise SecretNotFoundError(name)
    return dict(row)


def resolve_resource_access_context(user_context: Any = None):
    """Resolve request context for Vault ACL checks."""

    from storage import resource_access_service

    return resource_access_service.resolve_resource_access_context(user_context)


def _require_secret_resource_access(conn: Connection, row: dict[str, Any], user_context: Any) -> dict[str, Any]:
    """Return a secret row only when the caller may use its ACL resource."""

    from storage import resource_access_service

    resource_id = str(row.get("id") or "")
    if not resource_id or not resource_access_service.can_use_resource(
        user_context,
        "vault_secret",
        resource_id,
        connection=conn,
    ):
        raise VaultSecretAccessError("Vault secret access is not permitted.")
    return row


def _require_secret_resource_management(conn: Connection, row: dict[str, Any], user_context: Any) -> dict[str, Any]:
    """Return a secret row only when the caller may change its ACL resource."""

    from storage import resource_access_service

    context = resolve_resource_access_context(user_context)
    if not context.can_manage_instance:
        raise VaultSecretAccessError("Vault secret access is not permitted.")
    resource_id = str(row.get("id") or "")
    if not resource_id or not resource_access_service.can_manage_resource_acl(
        context,
        "vault_secret",
        resource_id,
        connection=conn,
    ):
        raise VaultSecretAccessError("Vault secret access is not permitted.")
    return row


def require_secret_create_access(*, user_context: Any = None):
    context = resolve_resource_access_context(user_context)
    if context.has_role("editor"):
        return context
    raise VaultSecretAccessError("Vault secret access is not permitted.")


def require_secret_access(conn: Connection, name: str, *, user_context: Any = None) -> dict[str, Any]:
    """Look up a secret by name and require access to its id-backed ACL resource."""

    return _require_secret_resource_access(conn, _require_row(conn, name), resolve_resource_access_context(user_context))


def _require_secret_names_access(
    conn: Connection,
    names: list[str],
    *,
    user_context: Any = None,
    management: bool = False,
) -> None:
    context = resolve_resource_access_context(user_context)
    if context.has_role("editor"):
        return
    member_names = sorted({str(name) for name in names if str(name)})
    if not member_names:
        raise VaultSecretAccessError("Vault secret access is not permitted.")
    secret_rows = {
        str(row["name"]): dict(row)
        for row in conn.execute(select(vault_secrets).where(vault_secrets.c.name.in_(member_names))).mappings()
    }
    if set(secret_rows) != set(member_names):
        raise VaultSecretAccessError("Vault secret access is not permitted.")
    require = _require_secret_resource_management if management else _require_secret_resource_access
    for name in member_names:
        require(conn, secret_rows[name], context)


def _require_grant_secret_access(
    conn: Connection,
    row: dict[str, Any],
    *,
    user_context: Any = None,
    management: bool = False,
) -> None:
    _require_secret_names_access(
        conn,
        _grant_member_names(row),
        user_context=user_context,
        management=management,
    )


def _register_created_secret_resource_policy(conn: Connection, secret_id: str, user_context: Any) -> None:
    """Register remote organization-created Vault secrets as private resources."""

    from storage import resource_access_service

    if not user_context.subject:
        return
    resource_access_service.ensure_resource_policy(
        conn,
        resource_kind="vault_secret",
        resource_id=secret_id,
        organization_id=user_context.organization_id,
        owner_user_id=user_context.subject,
        owner_email=user_context.email,
        access_level="private",
        created_by_user_id=user_context.subject,
        updated_by_user_id=user_context.subject,
    )


def _new_challenge() -> tuple[str, str]:
    challenge = secrets.token_bytes(32)
    return vault_webauthn.b64encode(challenge), vault_webauthn.challenge_hash(challenge)


def _challenge_expiry(ttl_seconds: int = DEFAULT_AUTHZ_CHALLENGE_TTL_SECONDS) -> str:
    return (datetime.now(timezone.utc) + timedelta(seconds=ttl_seconds)).isoformat()


def _stored_json_list(raw: str | None) -> list[str]:
    value = _loads(raw)
    if not isinstance(value, list):
        return []
    return [str(item) for item in value if isinstance(item, str) and item]


def _factor_payload(row: dict[str, Any]) -> dict[str, Any]:
    return {
        "id": row["id"],
        "kind": row.get("kind"),
        "label": row.get("label"),
        "rp_id": row.get("rp_id"),
        "credential_id": row.get("credential_id"),
        "alg": row.get("alg"),
        "transports": _stored_json_list(row.get("transports")),
        "created_at": row.get("created_at"),
        "last_used_at": row.get("last_used_at"),
    }


def _usable_webauthn_factor_rows(conn: Connection, *, rp_id: str) -> list[dict[str, Any]]:
    return [
        dict(row)
        for row in conn.execute(
            select(vault_auth_factors).where(
                vault_auth_factors.c.kind == "webauthn",
                vault_auth_factors.c.rp_id == rp_id,
                vault_auth_factors.c.disabled_at.is_(None),
            )
        ).mappings()
    ]


def _has_any_webauthn_factor(conn: Connection) -> bool:
    return (
        conn.execute(
            select(vault_auth_factors.c.id)
            .where(
                vault_auth_factors.c.kind == "webauthn",
                vault_auth_factors.c.disabled_at.is_(None),
            )
            .limit(1)
        ).first()
        is not None
    )


def list_webauthn_auth_factors(conn: Connection, *, rp_id: str | None = None) -> list[dict[str, Any]]:
    stmt = select(vault_auth_factors).where(
        vault_auth_factors.c.kind == "webauthn",
        vault_auth_factors.c.disabled_at.is_(None),
    )
    if rp_id:
        stmt = stmt.where(vault_auth_factors.c.rp_id == rp_id)
    return [_factor_payload(dict(row)) for row in conn.execute(stmt).mappings()]


def _challenge_row(conn: Connection, challenge_id: str, *, operation: str) -> dict[str, Any]:
    row = conn.execute(
        select(vault_operation_challenges).where(
            vault_operation_challenges.c.id == challenge_id,
            vault_operation_challenges.c.operation == operation,
        )
    ).mappings().first()
    if row is None:
        raise InvalidProtectedAuthzError("protected operation challenge was not found")
    return dict(row)


def _reject_unusable_challenge(row: dict[str, Any]) -> None:
    if row.get("consumed_at"):
        raise InvalidProtectedAuthzError("protected operation challenge was already used")
    expires_at = _parse_iso_datetime(row.get("expires_at"))
    if expires_at is None or expires_at <= datetime.now(timezone.utc):
        raise InvalidProtectedAuthzError("protected operation challenge expired")


def _consume_challenge(conn: Connection, challenge_id: str, *, factor_id: str) -> None:
    result = conn.execute(
        vault_operation_challenges.update()
        .where(vault_operation_challenges.c.id == challenge_id, vault_operation_challenges.c.consumed_at.is_(None))
        .values(consumed_at=_now(), factor_id=factor_id)
    )
    if result.rowcount != 1:
        raise InvalidProtectedAuthzError("protected operation challenge was already used")


def _create_webauthn_assertion_challenge(
    conn: Connection,
    *,
    operation: str,
    rp_id: str,
    origin: str,
    factors: list[dict[str, Any]],
    ttl_seconds: int,
) -> dict[str, Any]:
    challenge, challenge_digest = _new_challenge()
    challenge_id = _id("vop")
    expires_at = _challenge_expiry(ttl_seconds)
    conn.execute(
        vault_operation_challenges.insert().values(
            id=challenge_id,
            operation=operation,
            secret_name=None,
            secret_id=None,
            secret_updated_at=None,
            challenge_hash=challenge_digest,
            rp_id=rp_id,
            origin=origin,
            expires_at=expires_at,
            created_at=_now(),
        )
    )
    allow_credentials = []
    for factor in factors:
        credential: dict[str, Any] = {
            "type": "public-key",
            "id": factor["credential_id"],
            "factor_id": factor["id"],
        }
        transports = _stored_json_list(factor.get("transports"))
        if transports:
            credential["transports"] = transports
        allow_credentials.append(credential)
    return {
        "challenge_id": challenge_id,
        "expires_at": expires_at,
        "webauthn": {
            "challenge": challenge,
            "rpId": rp_id,
            "userVerification": "required",
            "allowCredentials": allow_credentials,
        },
    }


def _verify_webauthn_operation_authz(
    conn: Connection,
    payload: dict[str, Any] | None,
    *,
    operation: str,
    required_rp_id: str | None = None,
    required_origin: str | None = None,
) -> tuple[str, dict[str, Any]]:
    if not isinstance(payload, dict):
        raise ProtectedAuthRequiredError("protected operation requires WebAuthn authorization")
    if payload.get("kind") != "webauthn":
        raise InvalidProtectedAuthzError("protected operation requires WebAuthn authorization")
    challenge_id = str(payload.get("challenge_id") or "").strip()
    factor_id = str(payload.get("factor_id") or "").strip()
    if not challenge_id or not factor_id:
        raise InvalidProtectedAuthzError("protected operation authorization is incomplete")
    challenge = _challenge_row(conn, challenge_id, operation=operation)
    _reject_unusable_challenge(challenge)
    if required_rp_id is not None and challenge.get("rp_id") != required_rp_id:
        raise InvalidProtectedAuthzError("protected operation authorization RP mismatch")
    if required_origin is not None and challenge.get("origin") != required_origin:
        raise InvalidProtectedAuthzError("protected operation authorization origin mismatch")
    factor = conn.execute(
        select(vault_auth_factors).where(
            vault_auth_factors.c.id == factor_id,
            vault_auth_factors.c.kind == "webauthn",
            vault_auth_factors.c.disabled_at.is_(None),
        )
    ).mappings().first()
    if factor is None:
        raise InvalidProtectedAuthzError("protected operation authorization factor was not found")
    factor = dict(factor)
    if factor.get("rp_id") != challenge.get("rp_id"):
        raise InvalidProtectedAuthzError("protected operation authorization factor RP mismatch")
    assertion = payload.get("assertion")
    try:
        result = vault_webauthn.verify_assertion(
            assertion if isinstance(assertion, dict) else {},
            credential_id=str(factor["credential_id"]),
            public_key=str(factor["public_key"]),
            alg=int(factor["alg"]),
            stored_sign_count=int(factor.get("sign_count") or 0),
            expected_challenge_hash=str(challenge["challenge_hash"]),
            expected_origin=str(challenge["origin"]),
            rp_id=str(challenge["rp_id"]),
        )
    except vault_webauthn.WebAuthnVerificationError as exc:
        raise InvalidProtectedAuthzError(str(exc)) from exc
    now = _now()
    next_sign_count = max(int(factor.get("sign_count") or 0), result.sign_count)
    conn.execute(
        vault_auth_factors.update()
        .where(vault_auth_factors.c.id == factor_id)
        .values(sign_count=next_sign_count, last_used_at=now, updated_at=now)
    )
    _consume_challenge(conn, challenge_id, factor_id=factor_id)
    return factor_id, challenge


def create_webauthn_registration_options(
    conn: Connection,
    *,
    rp_id: str,
    origin: str,
    ttl_seconds: int = DEFAULT_AUTHZ_CHALLENGE_TTL_SECONDS,
) -> dict[str, Any]:
    challenge, challenge_digest = _new_challenge()
    challenge_id = _id("vop")
    expires_at = _challenge_expiry(ttl_seconds)
    now = _now()
    existing_factors = _usable_webauthn_factor_rows(conn, rp_id=rp_id)
    conn.execute(
        vault_operation_challenges.insert().values(
            id=challenge_id,
            operation="register_webauthn_factor",
            secret_name=None,
            secret_id=None,
            secret_updated_at=None,
            challenge_hash=challenge_digest,
            rp_id=rp_id,
            origin=origin,
            expires_at=expires_at,
            created_at=now,
        )
    )
    response = {
        "ok": True,
        "challenge_id": challenge_id,
        "expires_at": expires_at,
        "rp_id": rp_id,
        "origin": origin,
        "requires_existing_factor": bool(existing_factors),
        "webauthn": {
            "rp": {"name": "Avibe Vault", "id": rp_id},
            "user": {
                "id": vault_webauthn.b64encode(b"avibe-vault"),
                "name": "avibe-vault",
                "displayName": "Avibe Vault",
            },
            "challenge": challenge,
            "pubKeyCredParams": [
                {"type": "public-key", "alg": vault_webauthn.ALG_ES256},
                {"type": "public-key", "alg": vault_webauthn.ALG_RS256},
            ],
            "authenticatorSelection": {"residentKey": "required", "userVerification": "required"},
            "extensions": {"prf": {}},
        },
    }
    if existing_factors:
        response["authorization"] = _create_webauthn_assertion_challenge(
            conn,
            operation=AUTH_FACTOR_REGISTRATION_AUTHZ_OPERATION,
            rp_id=rp_id,
            origin=origin,
            factors=existing_factors,
            ttl_seconds=ttl_seconds,
        )
    return response


def register_webauthn_factor(
    conn: Connection,
    payload: dict[str, Any],
    *,
    rp_id: str | None = None,
    origin: str | None = None,
    establishment: bool = False,
) -> dict[str, Any]:
    if not isinstance(payload, dict):
        raise InvalidProtectedAuthzError("WebAuthn factor registration payload must be an object")
    challenge_id = str(payload.get("challenge_id") or "").strip()
    if not challenge_id:
        raise InvalidProtectedAuthzError("WebAuthn factor registration challenge_id is required")
    challenge = _challenge_row(conn, challenge_id, operation="register_webauthn_factor")
    _reject_unusable_challenge(challenge)
    challenge_rp_id = str(challenge.get("rp_id") or "")
    challenge_origin = str(challenge.get("origin") or "")
    if (rp_id is not None and challenge_rp_id != rp_id) or (origin is not None and challenge_origin != origin):
        raise InvalidProtectedAuthzError("WebAuthn factor registration origin mismatch")
    rp_id = rp_id or challenge_rp_id
    origin = origin or challenge_origin
    existing_factors = _usable_webauthn_factor_rows(conn, rp_id=rp_id)
    if establishment:
        if _has_any_webauthn_factor(conn):
            raise InvalidProtectedAuthzError("first WebAuthn factor can only be registered once during vault establishment")
    elif not existing_factors:
        raise ProtectedAuthzSetupRequiredError(
            "first WebAuthn factor must be registered during protected vault establishment; re-create this protected vault"
        )
    else:
        _verify_webauthn_operation_authz(
            conn,
            payload.get("authz") if isinstance(payload.get("authz"), dict) else None,
            operation=AUTH_FACTOR_REGISTRATION_AUTHZ_OPERATION,
            required_rp_id=rp_id,
            required_origin=origin,
        )
    credential = payload.get("credential")
    if not isinstance(credential, dict):
        raise InvalidProtectedAuthzError("WebAuthn factor registration credential is required")
    try:
        registration = vault_webauthn.verify_registration(
            credential,
            expected_challenge_hash=str(challenge["challenge_hash"]),
            expected_origin=origin,
            rp_id=rp_id,
        )
    except vault_webauthn.WebAuthnVerificationError as exc:
        raise InvalidProtectedAuthzError(str(exc)) from exc
    response = credential.get("response") if isinstance(credential.get("response"), dict) else {}
    transports = _string_list(response.get("transports"), field="transports") if "transports" in response else []
    label = _optional_string(payload.get("label"), field="label") if "label" in payload else None
    factor_id = _id("vaf")
    now = _now()
    try:
        conn.execute(
            vault_auth_factors.insert().values(
                id=factor_id,
                kind="webauthn",
                label=label,
                rp_id=rp_id,
                credential_id=registration.credential_id,
                public_key=registration.public_key,
                alg=registration.alg,
                sign_count=registration.sign_count,
                transports=json.dumps(transports) if transports else None,
                created_at=now,
                updated_at=now,
            )
        )
    except IntegrityError as exc:
        raise InvalidProtectedAuthzError("WebAuthn credential is already registered") from exc
    _consume_challenge(conn, challenge_id, factor_id=factor_id)
    audit(conn, "auth-factor-registered", delivery={"factor_id": factor_id, "kind": "webauthn", "rp_id": rp_id})
    row = conn.execute(select(vault_auth_factors).where(vault_auth_factors.c.id == factor_id)).mappings().one()
    return {"ok": True, "factor": _factor_payload(dict(row))}


def fulfill_pending_provision_requests_for_secret(
    conn: Connection,
    name: str,
    *,
    decided_at: str | None = None,
) -> int:
    result = conn.execute(
        vault_requests.update()
        .where(
            vault_requests.c.request_type == "provision",
            vault_requests.c.secret_name == name,
            vault_requests.c.status == "pending",
        )
        .values(status="fulfilled", decided_at=decided_at or _now(), callback_status="pending")
    )
    return int(result.rowcount or 0)


def create_secret(
    conn: Connection,
    *,
    name: str,
    sealed: Sealed,
    tags: list[str] | None = None,
    protection: str = "standard",
    kind: str = "static",
    signer_kind: str | None = None,
    description: str | None = None,
    source: str = "manual",
    policy: dict[str, Any] | None = None,
    public_meta: dict[str, Any] | None = None,
    fields: list[dict[str, Any]] | None = None,
    default_field: str | None = None,
    establishing_vmk: bool = False,
    authz_factor_registration: dict[str, Any] | None = None,
    authz_factor_origin: str | None = None,
    provision_request_id: str | None = None,
    user_context: Any = None,
) -> dict[str, Any]:
    """Create a secret from a caller-supplied encrypted envelope; return masked metadata.

    For ``standard`` secrets, the envelope is produced by the avault client. For
    ``protected`` secrets, the browser has already encrypted the value and built the
    opaque ``wrap_meta``. This layer never sees plaintext or keys, and stores no
    value-derived metadata.

    ``policy`` is a non-secret JSON dict (e.g. ``allowed_hosts`` + ``auth`` scheme for
    the brokered ``fetch`` mode); it never contains the value.
    """
    if not vault_crypto.is_valid_secret_name(name):
        raise InvalidSecretNameError(name)
    if protection not in {"standard", "protected"}:
        raise VaultServiceError(f"invalid protection tier: {protection!r}")
    if kind not in {"static", "keypair"}:
        raise VaultServiceError(f"invalid vault secret kind: {kind!r}")
    if kind != "keypair" and signer_kind is not None:
        raise VaultServiceError("signer_kind is only valid for keypair secrets")
    establishing_protected_vault = establishing_vmk and protection == "protected"
    if establishing_protected_vault:
        # This must be the transaction's first database access: a deferred SQLite
        # transaction cannot safely promote an older read snapshot after another
        # initializer commits. The row is only a mutex; protected-secret existence
        # remains the source of truth.
        lock_updated_at = _now()
        lock_stmt = sqlite_insert(state_meta).values(
            key=PROTECTED_VAULT_ESTABLISHMENT_LOCK_META_KEY,
            value_json="{}",
            updated_at=lock_updated_at,
        )
        conn.execute(
            lock_stmt.on_conflict_do_update(
                index_elements=[state_meta.c.key],
                set_={
                    "value_json": lock_stmt.excluded.value_json,
                    "updated_at": lock_stmt.excluded.updated_at,
                },
            )
        )
        if (
            conn.execute(select(vault_secrets.c.id).where(vault_secrets.c.protection == "protected").limit(1)).first()
            is not None
        ):
            raise VaultAlreadyInitializedError("a protected vault already exists; unlock it instead of re-initializing")

    provision_row, _existing_secret = _preflight_secret_create_name(
        conn,
        name=name,
        provision_request_id=provision_request_id,
    )

    if establishing_protected_vault:
        if not isinstance(authz_factor_registration, dict):
            raise ProtectedAuthzSetupRequiredError("protected vault establishment requires a passkey authorization factor")

    context = require_secret_create_access(user_context=user_context)
    secret_id = _id("vlt")
    now = _now()
    normalized_tags = _normalize_tags(tags)
    public_meta = dict(public_meta or {})
    if description:
        public_meta["description"] = description
    if kind == "keypair" and (fields or default_field is not None or "default_field" in public_meta):
        raise FieldsNotSupportedError("keypair secrets do not support fields or default_field")
    normalized_default_field = _default_field_name(value=default_field or public_meta.get("default_field"))
    if default_field is not None:
        _validate_field_name(default_field, field="default_field")
    raw_fields = [] if fields is None else fields
    if not isinstance(raw_fields, list):
        raise VaultServiceError("fields must be an array")
    if len(raw_fields) + 1 > MAX_SECRET_FIELDS:
        raise TooManyFieldsError(f"a vault secret can have at most {MAX_SECRET_FIELDS} fields")
    stored_fields: list[dict[str, Any]] = []
    field_names_seen: set[str] = {normalized_default_field}
    for raw_field in raw_fields:
        if not isinstance(raw_field, dict):
            raise VaultServiceError("fields entries must be objects")
        field_name = _validate_field_name(raw_field.get("name"), field="field name")
        if field_name in field_names_seen:
            raise FieldExistsError(f"field {field_name!r} already exists on {name}")
        if raw_field.get("record", f"{name}.{field_name}") != f"{name}.{field_name}":
            raise RecordMismatchError(f"record does not match field {field_name!r} on {name}")
        envelope = raw_field.get("sealed") or raw_field.get("envelope")
        if not isinstance(envelope, Sealed):
            raise VaultServiceError("fields entries require sealed envelopes")
        field_names_seen.add(field_name)
        stored_fields.append({
            "name": field_name,
            "ciphertext": envelope.ciphertext,
            "nonce": envelope.nonce,
            "wrap_meta": envelope.wrap_meta,
            "created_at": now,
            "updated_at": now,
        })
    if normalized_default_field == "value":
        public_meta.pop("default_field", None)
    else:
        public_meta["default_field"] = normalized_default_field
    try:
        conn.execute(
            vault_secrets.insert().values(
                id=secret_id,
                name=name,
                tags=json.dumps(normalized_tags) if normalized_tags else None,
                kind=kind,
                protection=protection,
                signer_kind=signer_kind,
                source=source,
                ciphertext=sealed.ciphertext,
                nonce=sealed.nonce,
                wrap_meta=sealed.wrap_meta,
                fields=json.dumps(stored_fields) if stored_fields else None,
                public_meta=json.dumps(public_meta) if public_meta else None,
                policy=json.dumps(policy) if policy else None,
                use_count=0,
                created_at=now,
                updated_at=now,
            )
        )
    except IntegrityError as exc:
        # Two concurrent creates (e.g. Web dialog + inline card) can both pass the
        # existence check above; the loser hits the exact UNIQUE(name) or the
        # folded-name unique index here. Re-read the winning name so callers keep
        # the same exact-duplicate vs case-conflict semantics instead of seeing a 500.
        existing_name = _find_secret_name_case_insensitive(conn, name)
        if existing_name is not None and existing_name != name:
            raise SecretNameCaseConflictError(name, existing_name) from exc
        raise SecretExistsError(name) from exc
    _register_created_secret_resource_policy(conn, secret_id, context)
    audit(conn, "created", secret_name=name)
    if establishing_vmk and protection == "protected":
        # Vestigial after protected-delete authz was removed: the sandbox still
        # submits this registration until the setup-time authz flow is cleaned up.
        register_webauthn_factor(
            conn,
            authz_factor_registration or {},
            origin=authz_factor_origin,
            establishment=True,
        )
    decided_at = _now()
    if provision_row is not None:
        result = conn.execute(
            vault_requests.update()
            .where(vault_requests.c.id == provision_row["id"], vault_requests.c.status == "pending")
            .values(status="fulfilled", decided_at=decided_at, callback_status="pending")
        )
        if result.rowcount != 1:
            raise InvalidRequestError("provision request is not pending")
    # Once the secret exists, every same-name pending provision ask is satisfied. A
    # request-specific create still uses only that request's spec for the secret metadata,
    # but sibling waiters should not keep timing out or resurfacing stale rows.
    fulfill_pending_provision_requests_for_secret(conn, name, decided_at=decided_at)
    return _meta_payload(_require_row(conn, name))


def link_secret_to_skills(conn: Connection, secret_name: str, skills: list[str], *, source: str = "agent") -> None:
    if not skills:
        return
    row = _require_row(conn, secret_name)
    current = _row_tags(row)
    updated = list(dict.fromkeys([*current, *(skill_tag(skill) for skill in skills if skill and skill.strip())]))
    if updated == current:
        return
    conn.execute(
        vault_secrets.update()
        .where(vault_secrets.c.name == secret_name)
        .values(tags=json.dumps(updated) if updated else None)
    )
    audit(conn, "tags-updated", secret_name=secret_name, delivery={"source": source, "tags": updated})


def update_secret_tags(
    conn: Connection,
    secret_name: str,
    tags: list[str],
    *,
    user_context: Any = None,
) -> dict[str, Any]:
    context = resolve_resource_access_context(user_context)
    row = _require_secret_resource_management(conn, _require_row(conn, secret_name), context)
    normalized = _normalize_tags(tags)
    conn.execute(
        vault_secrets.update()
        .where(vault_secrets.c.name == secret_name)
        .values(tags=json.dumps(normalized) if normalized else None)
    )
    audit(conn, "tags-updated", secret_name=secret_name, delivery={"tags": normalized})
    return _meta_payload(dict(row) | {"tags": json.dumps(normalized) if normalized else None})


def update_secret_metadata(
    conn: Connection,
    secret_name: str,
    *,
    description: Any = _UNSET,
    tags: Any = _UNSET,
    policy: Any = _UNSET,
    default_field: Any = _UNSET,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    release_scopes: list[dict[str, str]] | None = None,
    user_context: Any = None,
) -> dict[str, Any]:
    """Update value-free metadata only.

    Tags and display metadata deliberately do not expire active grants: grants are
    scoped to a frozen secret set, not to selectors. Fetch policy is an
    authorization boundary, so policy changes expire relevant requests/grants.
    """

    context = resolve_resource_access_context(user_context)
    row = _require_secret_resource_management(conn, _require_row(conn, secret_name), context)
    values: dict[str, Any] = {}
    fields: list[str] = []
    public_meta: dict[str, Any] | None = None
    policy_changed = False

    if description is not _UNSET:
        public_meta = _public_meta(row.get("public_meta"))
        normalized_description = _optional_string(description, field="description")
        if normalized_description:
            public_meta["description"] = normalized_description
        else:
            public_meta.pop("description", None)
        fields.append("description")

    if tags is not _UNSET:
        normalized_tags = _normalize_tags(_string_list(tags, field="tags"))
        values["tags"] = json.dumps(normalized_tags) if normalized_tags else None
        fields.append("tags")

    if default_field is not _UNSET:
        if row.get("kind") == "keypair":
            raise FieldsNotSupportedError("keypair secrets do not support default_field")
        normalized_default = _validate_field_name(default_field, field="default_field")
        extras = _extra_field_rows(row, strict=True)
        existing_default = _default_field_name(row)
        if normalized_default != existing_default:
            if normalized_default in {str(item["name"]) for item in extras}:
                raise FieldExistsError(f"field {normalized_default!r} already exists on {secret_name}")
            if public_meta is None:
                public_meta = _public_meta(row.get("public_meta"))
            if normalized_default == "value":
                public_meta.pop("default_field", None)
            else:
                public_meta["default_field"] = normalized_default
            fields.append("default_field")

    if policy is not _UNSET:
        if policy is None:
            policy = {}
        if not isinstance(policy, dict):
            raise VaultServiceError("policy must be an object")
        existing_policy = _secret_policy(row)
        internal_policy_keys = set(existing_policy) - PROVISION_SPEC_ALLOWED_POLICY_KEYS
        incoming_internal_keys = set(policy) - PROVISION_SPEC_ALLOWED_POLICY_KEYS
        unsupported_internal_keys = incoming_internal_keys - internal_policy_keys
        if unsupported_internal_keys:
            raise VaultServiceError(f"unsupported policy fields: {', '.join(sorted(unsupported_internal_keys))}")
        changed_internal_keys = [key for key in sorted(incoming_internal_keys) if policy.get(key) != existing_policy.get(key)]
        if changed_internal_keys:
            raise VaultServiceError(f"policy.{changed_internal_keys[0]} is read-only")
        # Preserve internal policy keys such as always_ask; metadata editing owns
        # only the user-visible fetch policy fields.
        preserved_policy = {
            key: value
            for key, value in existing_policy.items()
            if key not in PROVISION_SPEC_ALLOWED_POLICY_KEYS
        }
        existing_visible_policy = _stored_fetch_policy_visible_snapshot(existing_policy)
        normalized_policy = _normalize_fetch_policy(policy, field="policy", allowed_extra_keys=internal_policy_keys)
        next_policy = {**preserved_policy, **normalized_policy}
        values["policy"] = json.dumps(next_policy) if next_policy else None
        fields.append("policy")
        if normalized_policy != existing_visible_policy:
            policy_changed = True

    if public_meta is not None:
        values["public_meta"] = json.dumps(public_meta) if public_meta else None

    if not values:
        return _meta_payload(row)

    # Display metadata does not change the envelopes or their approval versions.
    # Compare the written columns as well, since those edits share that version.
    compared_columns = list(values)
    result = conn.execute(
        vault_secrets.update()
        .where(
            vault_secrets.c.id == row["id"],
            vault_secrets.c.updated_at == row["updated_at"],
            *(vault_secrets.c[key] == row.get(key) for key in compared_columns),
        )
        .values(**values)
    )
    if result.rowcount != 1:
        raise SecretConflictError(f"secret {secret_name!r} changed while metadata was being updated")
    if policy_changed:
        policy_grant_rows = active_grant_rows_for_secret(conn, secret_name)
        _expire_pending_requests_for_secret(conn, secret_name, reason="request-expired-policy-changed")
        _expire_grant_rows(conn, policy_grant_rows, cache=cache, reason="grant-expired-policy-changed")
        if release_scopes is not None:
            release_scopes.extend(agent_release_scopes_after_rows(conn, policy_grant_rows, cache=cache))
    audit(conn, "metadata-updated", secret_name=secret_name, delivery={"fields": fields})
    return _meta_payload(_require_row(conn, secret_name))


def update_secret_classification(
    conn: Connection,
    secret_name: str,
    *,
    kind: str | None = None,
    protection: str | None = None,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    user_context: Any = None,
) -> dict[str, Any]:
    context = resolve_resource_access_context(user_context)
    row = _require_secret_resource_management(conn, _require_row(conn, secret_name), context)
    values: dict[str, Any] = {}
    if kind is not None:
        normalized_kind = kind.strip().lower()
        if normalized_kind not in {"static", "keypair"}:
            raise VaultServiceError(f"invalid vault secret kind: {kind!r}")
        values["kind"] = normalized_kind
    if protection is not None:
        normalized_protection = protection.strip().lower()
        if normalized_protection not in {"standard", "protected"}:
            raise VaultServiceError(f"invalid protection tier: {protection!r}")
        values["protection"] = normalized_protection
    if not values:
        return _meta_payload(row)
    if values.get("kind", row.get("kind")) != row.get("kind") or values.get("protection", row.get("protection")) != row.get("protection"):
        _expire_pending_requests_for_secret(conn, secret_name, reason="request-expired-classification-changed")
        _expire_active_grants_for_secret(conn, secret_name, cache=cache, reason="grant-expired-classification-changed")
    values["updated_at"] = _now()
    conn.execute(vault_secrets.update().where(vault_secrets.c.name == secret_name).values(**values))
    audit(conn, "updated", secret_name=secret_name, delivery={"fields": sorted(values)})
    return _meta_payload(_require_row(conn, secret_name))


def get_secret_meta(conn: Connection, name: str, *, user_context: Any = None) -> dict[str, Any]:
    return _meta_payload(require_secret_access(conn, name, user_context=user_context))


def get_secret_resource_metadata(conn: Connection, resource_id: str) -> dict[str, str] | None:
    """Return value-free Vault metadata allowed in the hosted resource index."""

    row = conn.execute(
        select(vault_secrets.c.name, vault_secrets.c.updated_at)
        .where(vault_secrets.c.id == resource_id)
        .limit(1)
    ).mappings().first()
    if row is None:
        return None
    return {
        "display_name": str(row["name"]),
        "updated_at": str(row["updated_at"]),
    }


def get_signing_public_key(conn: Connection, name: str, *, user_context: Any = None) -> dict[str, Any] | None:
    """Raw pinned signing public key ({curve, public_key}) from storage.

    The masked meta payload exposes only derived addresses (not the raw key), so
    server-side signature verification reads the pinned key from here instead.
    Returns ``None`` when the secret has no pinned signing key.
    """
    public_meta = _public_meta(require_secret_access(conn, name, user_context=user_context).get("public_meta"))
    signing_public_key = public_meta.get("signing_public_key")
    return signing_public_key if isinstance(signing_public_key, dict) else None


def store_pubkey_pin(
    conn: Connection,
    name: str,
    pin: dict[str, Any],
    *,
    user_context: Any = None,
) -> dict[str, Any]:
    """Store avault pubkey pin/attestation metadata without touching value fields."""
    context = resolve_resource_access_context(user_context)
    row = _require_secret_resource_management(conn, _require_row(conn, name), context)
    public_meta = _public_meta(row.get("public_meta"))
    public_meta["avault_pubkey_pin"] = {
        key: value
        for key, value in pin.items()
        if key in {"public_key", "fingerprint", "attested_at", "attestation"}
    }
    result = conn.execute(
        vault_secrets.update()
        .where(
            vault_secrets.c.id == row["id"],
            vault_secrets.c.updated_at == row["updated_at"],
            vault_secrets.c.public_meta == row.get("public_meta"),
        )
        .values(public_meta=json.dumps(public_meta))
    )
    if result.rowcount != 1:
        raise SecretConflictError(f"secret {name!r} changed while metadata was being updated")
    audit(
        conn,
        "pubkey_pinned",
        secret_name=name,
        delivery={"fingerprint": public_meta["avault_pubkey_pin"].get("fingerprint")},
    )
    return get_secret_meta(conn, name, user_context=context)


def _normalize_secret_filter_values(values: list[str] | None, *, field: str) -> list[str]:
    out: list[str] = []
    for raw in values or []:
        for item in str(raw).split(","):
            stripped = item.strip()
            if stripped:
                out.append(stripped)
    if field == "tags":
        return _normalize_tags(out)
    return out


def _searchable_secret_text(secret: dict[str, Any]) -> str:
    """Build a value-free search blob for Vault metadata queries."""

    fields: list[Any] = [
        secret.get("name"),
        secret.get("kind"),
        secret.get("protection"),
        secret.get("signer_kind"),
        secret.get("description"),
        secret.get("tags"),
        secret.get("default_field"),
        secret.get("fields"),
        secret_record_names(secret),
        f"{secret.get('name')}.{secret.get('default_field') or 'value'}",
    ]
    policy = secret.get("policy")
    if isinstance(policy, dict):
        fields.append(policy.get("allowed_hosts"))
        auth = policy.get("auth")
        if isinstance(auth, dict):
            fields.extend([auth.get("type"), auth.get("name")])
    addresses = secret.get("signing_addresses")
    if isinstance(addresses, dict):
        fields.append(addresses)
    return json.dumps(fields, sort_keys=True, default=str).lower()


def _matches_secret_query(secret: dict[str, Any], query: str | None) -> bool:
    raw = (query or "").strip().lower()
    if not raw:
        return True
    haystack = _searchable_secret_text(secret)
    return all(term in haystack for term in raw.split())


def list_secrets(
    conn: Connection,
    *,
    tag: str | None = None,
    tags: list[str] | None = None,
    query: str | None = None,
    kind: str | None = None,
    protection: str | None = None,
    user_context: Any = None,
) -> list[dict[str, Any]]:
    """Masked, value-free list. Never decrypts."""
    from storage import resource_access_service

    context = resolve_resource_access_context(user_context)
    stmt = select(vault_secrets).order_by(vault_secrets.c.name)
    raw_rows = [dict(row) for row in conn.execute(stmt).mappings()]
    accessible_rows = resource_access_service.filter_accessible_resources(
        context,
        "vault_secret",
        raw_rows,
        connection=conn,
    )
    rows = [_meta_payload(row) for row in accessible_rows]
    normalized_tags = _normalize_secret_filter_values([tag] if tag is not None else [], field="tags")
    normalized_tags.extend(_normalize_secret_filter_values(tags, field="tags"))
    normalized_tags = list(dict.fromkeys(normalized_tags))
    if normalized_tags:
        rows = [row for row in rows if all(normalized in row.get("tags", []) for normalized in normalized_tags)]
    normalized_kind = (kind or "").strip().lower()
    if normalized_kind:
        if normalized_kind not in {"static", "keypair"}:
            raise VaultServiceError("kind must be static or keypair")
        rows = [row for row in rows if row.get("kind") == normalized_kind]
    normalized_protection = (protection or "").strip().lower()
    if normalized_protection:
        if normalized_protection not in {"standard", "protected"}:
            raise VaultServiceError("protection must be standard or protected")
        rows = [row for row in rows if row.get("protection") == normalized_protection]
    rows = [row for row in rows if _matches_secret_query(row, query)]
    return rows


def list_secret_tags(
    conn: Connection,
    *,
    query: str | None = None,
    tag_type: str | None = None,
    user_context: Any = None,
) -> list[dict[str, Any]]:
    """Return value-free tag inventory with secret counts."""

    normalized_type = (tag_type or "").strip().lower()
    if normalized_type and normalized_type not in {"tag", "skill"}:
        raise VaultServiceError("tag type must be tag or skill")
    counts: dict[str, int] = {}
    for secret in list_secrets(conn, user_context=user_context):
        for tag in secret.get("tags", []):
            if isinstance(tag, str) and tag:
                counts[tag] = counts.get(tag, 0) + 1
    rows: list[dict[str, Any]] = []
    raw_query = (query or "").strip().lower()
    for tag, count in counts.items():
        is_skill = tag.startswith(SKILL_TAG_PREFIX)
        kind = "skill" if is_skill else "tag"
        if normalized_type and kind != normalized_type:
            continue
        skill = tag[len(SKILL_TAG_PREFIX) :] if is_skill else None
        haystack = " ".join(part for part in [tag, skill, kind] if part).lower()
        if raw_query and not all(term in haystack for term in raw_query.split()):
            continue
        payload = {"tag": tag, "type": kind, "secret_count": count}
        if skill:
            payload["skill"] = skill
        rows.append(payload)
    return sorted(rows, key=lambda item: (item["type"] != "tag", item["tag"].lower()))


def latest_protected_vmk_wrap_meta(conn: Connection) -> str | None:
    """Return the newest protected-tier VMK wrap metadata as opaque JSON text."""
    return conn.execute(
        select(vault_secrets.c.wrap_meta)
        .where(vault_secrets.c.protection == "protected", vault_secrets.c.wrap_meta.is_not(None))
        .order_by(vault_secrets.c.updated_at.desc(), vault_secrets.c.created_at.desc())
        .limit(1)
    ).scalar_one_or_none()


def rotate_secret(
    conn: Connection,
    name: str,
    sealed: Sealed,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    user_context: Any = None,
) -> dict[str, Any]:
    context = resolve_resource_access_context(user_context)
    row = _require_secret_resource_management(conn, _require_row(conn, name), context)
    _extra_field_rows(row, strict=True)
    public_meta = _public_meta(row.get("public_meta"))
    public_meta.pop("preview", None)
    result = conn.execute(
        vault_secrets.update()
        .where(
            vault_secrets.c.id == row["id"],
            vault_secrets.c.updated_at == row["updated_at"],
            vault_secrets.c.public_meta == row.get("public_meta"),
        )
        .values(
            ciphertext=sealed.ciphertext,
            nonce=sealed.nonce,
            wrap_meta=sealed.wrap_meta,
            public_meta=json.dumps(public_meta) if public_meta else None,
            updated_at=_next_updated_at(str(row.get("updated_at") or "")),
        )
    )
    if result.rowcount != 1:
        raise SecretConflictError(f"secret {name!r} changed while its value was being updated")
    _expire_pending_requests_for_secret(conn, name, reason="request-expired-envelope-changed")
    _expire_active_grants_for_secret(conn, name, cache=cache, reason="grant-expired-envelope-changed")
    audit(conn, "updated", secret_name=name)
    return _meta_payload(_require_row(conn, name))


def _expire_envelope_change(
    conn: Connection,
    secret_name: str,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    release_scopes: list[dict[str, str]] | None = None,
) -> None:
    _expire_pending_requests_for_secret(conn, secret_name, reason="request-expired-envelope-changed")
    grant_rows = active_grant_rows_for_secret(conn, secret_name)
    _expire_grant_rows(conn, grant_rows, cache=cache, reason="grant-expired-envelope-changed")
    if release_scopes is not None:
        release_scopes.extend(agent_release_scopes_after_rows(conn, grant_rows, cache=cache))


def _stored_fields_json(fields: list[dict[str, Any]]) -> str | None:
    return json.dumps(fields) if fields else None


def _require_field_record(row: dict[str, Any], field_name: str, record: str) -> None:
    expected = record_name_for_field(str(row["name"]), field_name, default_field=_default_field_name(row))
    if record != expected:
        raise RecordMismatchError(f"record does not match field {field_name!r} on {row['name']}")


def update_secret_field(
    conn: Connection,
    secret_name: str,
    field_name: str,
    sealed: Sealed,
    *,
    record: str,
    expected_updated_at: str | None = None,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    release_scopes: list[dict[str, str]] | None = None,
    user_context: Any = None,
) -> dict[str, Any]:
    context = resolve_resource_access_context(user_context)
    row = _require_secret_resource_management(conn, _require_row(conn, secret_name), context)
    field_name = _validate_field_name(field_name)
    snapshot_updated_at = row.get("updated_at")
    if expected_updated_at is not None and snapshot_updated_at != expected_updated_at:
        raise SecretConflictError(f"secret {secret_name!r} changed while the field was being updated")
    if row.get("kind") == "keypair":
        raise FieldsNotSupportedError(f"{secret_name} does not support fields")
    _require_field_record(row, field_name, record)
    default_field = _default_field_name(row)
    extras = _extra_field_rows(row, strict=True)
    extra_by_name = {str(item["name"]): item for item in extras}
    now = _next_updated_at(snapshot_updated_at)
    if field_name == default_field:
        values = {"ciphertext": sealed.ciphertext, "nonce": sealed.nonce, "wrap_meta": sealed.wrap_meta}
        op = "replace"
    else:
        existing = extra_by_name.get(field_name)
        if existing is None:
            if len(extras) + 1 >= MAX_SECRET_FIELDS:
                raise TooManyFieldsError(f"a vault secret can have at most {MAX_SECRET_FIELDS} fields")
            extras.append({
                "name": field_name,
                "ciphertext": sealed.ciphertext,
                "nonce": sealed.nonce,
                "wrap_meta": sealed.wrap_meta,
                "created_at": now,
                "updated_at": now,
            })
            op = "add"
        else:
            existing.update({"ciphertext": sealed.ciphertext, "nonce": sealed.nonce, "wrap_meta": sealed.wrap_meta, "updated_at": now})
            op = "replace"
        values = {"fields": _stored_fields_json(extras)}
    values["updated_at"] = now
    stmt = vault_secrets.update().where(
        vault_secrets.c.id == row["id"],
        vault_secrets.c.updated_at == snapshot_updated_at,
        vault_secrets.c.public_meta == row.get("public_meta"),
    )
    result = conn.execute(stmt.values(**values))
    if result.rowcount != 1:
        # A rename can race this transaction after its initial read without
        # changing updated_at. Never store an envelope under the wrong record.
        current = _require_row(conn, secret_name)
        if current.get("id") == row.get("id"):
            _require_field_record(current, field_name, record)
        raise SecretConflictError(f"secret {secret_name!r} changed while the field was being updated")
    _expire_envelope_change(conn, secret_name, cache=cache, release_scopes=release_scopes)
    audit(conn, "updated", secret_name=secret_name, delivery={"field": field_name, "op": op})
    return _meta_payload(_require_row(conn, secret_name))


def remove_secret_field(
    conn: Connection,
    secret_name: str,
    field_name: str,
    *,
    expected_updated_at: str | None = None,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    release_scopes: list[dict[str, str]] | None = None,
    user_context: Any = None,
) -> dict[str, Any]:
    context = resolve_resource_access_context(user_context)
    row = _require_secret_resource_management(conn, _require_row(conn, secret_name), context)
    field_name = _validate_field_name(field_name)
    snapshot_updated_at = row.get("updated_at")
    if expected_updated_at is not None and snapshot_updated_at != expected_updated_at:
        raise SecretConflictError(f"secret {secret_name!r} changed while the field was being removed")
    if row.get("kind") == "keypair":
        raise FieldsNotSupportedError(f"{secret_name} does not support fields")
    if field_name == _default_field_name(row):
        raise InvalidRequestError("the default field cannot be removed")
    extras = _extra_field_rows(row, strict=True)
    if not any(str(item["name"]) == field_name for item in extras):
        raise FieldNotFoundError(f"field {field_name!r} not found on {secret_name}; fields: {', '.join(secret_field_names(row))}")
    extras = [item for item in extras if str(item["name"]) != field_name]
    stmt = vault_secrets.update().where(
        vault_secrets.c.id == row["id"],
        vault_secrets.c.updated_at == snapshot_updated_at,
    )
    result = conn.execute(
        stmt.values(
            fields=_stored_fields_json(extras),
            updated_at=_next_updated_at(str(snapshot_updated_at or "")),
        )
    )
    if result.rowcount != 1:
        raise SecretConflictError(f"secret {secret_name!r} changed while the field was being removed")
    _expire_envelope_change(conn, secret_name, cache=cache, release_scopes=release_scopes)
    audit(conn, "updated", secret_name=secret_name, delivery={"field": field_name, "op": "remove"})
    return _meta_payload(_require_row(conn, secret_name))


def _disable_webauthn_factors_if_vault_deestablished(conn: Connection) -> None:
    protected_row = conn.execute(
        select(vault_secrets.c.id).where(vault_secrets.c.protection == "protected").limit(1)
    ).first()
    if protected_row is not None:
        return
    now = _now()
    result = conn.execute(
        vault_auth_factors.update()
        .where(vault_auth_factors.c.kind == "webauthn", vault_auth_factors.c.disabled_at.is_(None))
        .values(disabled_at=now, updated_at=now)
    )
    disabled_count = int(result.rowcount or 0)
    if disabled_count:
        audit(conn, "auth-factors-disabled", delivery={"reason": "vault-deestablished", "count": disabled_count})


def delete_secret(
    conn: Connection,
    name: str,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    user_context: Any = None,
) -> None:
    from storage import resource_access_service

    context = resolve_resource_access_context(user_context)
    row = _require_secret_resource_management(conn, _require_row(conn, name), context)
    audit_snapshot = _build_audit_access_snapshot(conn, [name])
    pending_delete_ids: list[str] = []
    pending_rows = conn.execute(
        select(vault_requests).where(
            vault_requests.c.request_type == "delete",
            vault_requests.c.secret_name == name,
            vault_requests.c.status == "pending",
        )
    ).mappings().all()
    for pending_row in pending_rows:
        settled_row, _ = _expire_request_if_due(conn, dict(pending_row))
        if settled_row.get("status") == "pending":
            pending_delete_ids.append(str(settled_row["id"]))
    # Claim the rows with a portable SELECT + UPDATE pair. Do not use DML RETURNING:
    # Avibe supports Python versions whose system SQLite may predate SQLite 3.35.
    decided_at = _now()
    claimed_ids: list[str] = []
    for request_id in pending_delete_ids:
        result = conn.execute(
            vault_requests.update()
            .where(vault_requests.c.id == request_id, vault_requests.c.status == "pending")
            .values(status="fulfilled", decided_at=decided_at, callback_status="pending")
        )
        if result.rowcount == 1:
            claimed_ids.append(str(request_id))
    for request_id in claimed_ids:
        audit(conn, "delete-fulfilled", secret_name=name, request_id=request_id, access_snapshot=audit_snapshot)
    _expire_pending_requests_for_secret(conn, name, reason="request-expired-envelope-changed")
    _expire_active_grants_for_secret(conn, name, cache=cache, reason="grant-expired-envelope-changed")
    conn.execute(vault_secrets.delete().where(vault_secrets.c.name == name))
    resource_access_service.delete_resource_policy(conn, "vault_secret", str(row["id"]))
    if row.get("protection") == "protected":
        _disable_webauthn_factors_if_vault_deestablished(conn)
    audit(conn, "deleted", secret_name=name, access_snapshot=audit_snapshot)


def get_secret_policy(conn: Connection, name: str, *, user_context: Any = None) -> dict[str, Any]:
    """Return the secret's non-secret policy dict (allowed_hosts, auth scheme)."""
    row, _entry = _resolve_record_ref(conn, name, user_context=user_context)
    return _loads(row.get("policy")) or {}


def get_envelope(conn: Connection, name: str, *, user_context: Any = None) -> Sealed:
    """Return one standard-tier record envelope for ``NAME`` or ``NAME.field``."""
    row, entry = _resolve_record_ref(conn, name, user_context=user_context)
    if row.get("protection") != "standard":
        raise UnsupportedProtectionError(f"{name} is protected-tier; use resident-agent grant delivery")
    _reject_keypair_value_delivery(row, str(row["name"]))
    return entry["envelope"]


def get_protected_envelope(conn: Connection, name: str, *, user_context: Any = None) -> Sealed:
    row, entry = _resolve_record_ref(conn, name, user_context=user_context)
    if row.get("protection") != "protected":
        raise UnsupportedProtectionError(f"{name} is standard-tier")
    _reject_keypair_value_delivery(row, str(row["name"]))
    return entry["envelope"]


def get_protected_record_envelope(conn: Connection, name: str, *, user_context: Any = None) -> Sealed:
    return get_protected_envelope(conn, name, user_context=user_context)


def record_proxy_use(conn: Connection, identity: DeliveryIdentity, *, requester: Any = None, delivery: Any = None) -> None:
    """Record an actual egress from its pre-handoff identity, even after deletion."""
    conn.execute(
        vault_secrets.update()
        .where(vault_secrets.c.id == identity.secret_id)
        .values(last_used_at=_now(), use_count=vault_secrets.c.use_count + 1)
    )
    delivery_payload = dict(delivery) if isinstance(delivery, dict) else {}
    delivery_payload["field"] = identity.field
    audit(conn, "proxied", secret_name=identity.name, requester=requester, delivery=delivery_payload, access_snapshot=identity.access_snapshot)


def record_signing_use(
    conn: Connection,
    name: str,
    *,
    requester: Any = None,
    delivery: Any = None,
    request_id: str | None = None,
) -> None:
    """Bump signing key usage + write a value-free ``signed`` audit row."""
    _require_row(conn, name)
    conn.execute(
        vault_secrets.update()
        .where(vault_secrets.c.name == name)
        .values(last_used_at=_now(), use_count=vault_secrets.c.use_count + 1)
    )
    audit(conn, "signed", secret_name=name, requester=requester, delivery=delivery, request_id=request_id)


def record_reveal_use(
    conn: Connection,
    name: str,
    *,
    requester: Any = None,
    delivery: Any = None,
    request_id: str | None = None,
) -> None:
    """Bump revealed secret usage + write a value-free ``revealed`` audit row."""
    row, entry = _resolve_record_ref(conn, name)
    secret_name = str(row["name"])
    conn.execute(
        vault_secrets.update()
        .where(vault_secrets.c.name == secret_name)
        .values(last_used_at=_now(), use_count=vault_secrets.c.use_count + 1)
    )
    delivery_payload = dict(delivery) if isinstance(delivery, dict) else {}
    delivery_payload["field"] = str(entry["field"])
    audit(
        conn,
        "revealed",
        secret_name=secret_name,
        requester=requester,
        delivery=delivery_payload,
        request_id=request_id,
    )


def get_envelopes(conn: Connection, names: list[str], *, user_context: Any = None) -> dict[str, Sealed]:
    """Return the stored envelopes for the requested secrets (standard tier; no decrypt).

    Validates the WHOLE batch (all names exist + standard tier) BEFORE returning any, so a
    missing/protected name fails the request as a unit. The caller hands these envelopes to
    the avault client to deliver (child env / file), and records delivery via
    :func:`record_deliveries` only after the delivery side effect succeeds, so a failed
    delivery never shows as delivered. This layer never decrypts.
    """
    context = resolve_resource_access_context(user_context)
    out: dict[str, Sealed] = {}
    for ref in names:
        row, entry = _resolve_record_ref(conn, ref, user_context=context)
        if row.get("protection") != "standard":
            raise UnsupportedProtectionError(f"{ref} is protected-tier; use resident-agent grant delivery")
        _reject_keypair_value_delivery(row, str(row["name"]))
        out[str(entry["name"])] = entry["envelope"]
    return out


def get_key_envelope(conn: Connection, name: str, *, user_context: Any = None) -> Sealed:
    """Return a locally-stored key envelope for signing.

    This is still envelope-only; the caller hands it to avault (standard tier) or to
    browser-side signing (protected tier). The private key never returns to Python.
    """
    row = require_secret_access(conn, name, user_context=user_context)
    if row.get("ciphertext") is None or row.get("nonce") is None or row.get("wrap_meta") is None:
        raise VaultServiceError(f"{name} does not have a local key envelope")
    return _row_sealed(row)


def get_signing_envelope(conn: Connection, name: str, *, user_context: Any = None) -> Sealed:
    row = require_secret_access(conn, name, user_context=user_context)
    if row.get("kind") != "keypair":
        raise InvalidRequestError(f"{name} is not a signing key")
    if row.get("signer_kind") not in (None, "local"):
        raise InvalidRequestError(f"{name} is not locally signable")
    return get_key_envelope(conn, name, user_context=user_context)


def capture_delivery_identities(conn: Connection, refs: list[str], *, user_context: Any = None) -> list[DeliveryIdentity]:
    """Capture labels and ACL identity while the selected records still exist."""
    identities: list[DeliveryIdentity] = []
    snapshots: dict[str, dict[str, Any] | None] = {}
    for ref in refs:
        row, entry = _resolve_record_ref(conn, ref, user_context=user_context)
        name = str(row["name"])
        if name not in snapshots:
            snapshots[name] = _build_audit_access_snapshot(conn, [name])
        identities.append(DeliveryIdentity(str(row["id"]), name, str(entry["field"]), snapshots[name]))
    return identities


def record_deliveries(conn: Connection, identities: list[DeliveryIdentity], *, requester: Any = None, mode: str | None = None) -> None:
    """Bookkeep a completed handoff without resolving records a second time."""
    delivered: dict[str, tuple[DeliveryIdentity, list[str]]] = {}
    for identity in identities:
        _, fields = delivered.setdefault(identity.secret_id, (identity, []))
        if identity.field not in fields:
            fields.append(identity.field)
    for identity, fields in delivered.values():
        conn.execute(
            vault_secrets.update()
            .where(vault_secrets.c.id == identity.secret_id)
            .values(last_used_at=_now(), use_count=vault_secrets.c.use_count + 1)
        )
        audit(
            conn,
            "delivered",
            secret_name=identity.name,
            requester=requester,
            delivery={"mode": mode, "fields": fields},
            access_snapshot=identity.access_snapshot,
        )


def _active_session_turn_anchor(
    conn: Connection,
    session_id: str | None,
) -> tuple[str | None, str | None]:
    """Return the current Turn's durable message and Turn identities.

    Claude's SDK client keeps one session-level caller environment, so a command
    spawned during a later turn cannot carry that turn's native message id. The
    durable Turn/initial Delivery already owns the identity we need and is safe to
    use while the turn is starting or active. A message id is returned only after
    acceptance has materialized it; the Turn id remains usable before then.
    """
    identity = str(session_id or "").strip()
    if not identity:
        return None, None
    row = conn.execute(
        select(
            session_turns.c.id.label("turn_id"),
            message_deliveries.c.message_id,
        )
        .join(
            message_deliveries,
            message_deliveries.c.id == session_turns.c.initial_delivery_id,
        )
        .where(session_turns.c.session_id == identity)
        .where(session_turns.c.state.in_(("starting", "active")))
        .order_by(session_turns.c.updated_at.desc(), session_turns.c.id.desc())
        .limit(1)
    ).mappings().first()
    if row is None:
        return None, None
    message_id = str(row.get("message_id") or "").strip() or None
    turn_id = str(row.get("turn_id") or "").strip() or None
    return message_id, turn_id


def create_provision_request(
    conn: Connection,
    name: str,
    *,
    reason: str | None = None,
    spec: dict[str, Any] | None = None,
    requester: Any = None,
    message_id: str | None = None,
    user_context: Any = None,
) -> dict[str, Any]:
    """Record an agent's request for a missing secret (dynamic ask).

    If the secret already exists, the request is born ``fulfilled`` — otherwise a
    ``request --wait`` would block forever (a create for an existing name is rejected,
    so nothing would ever flip a pending row).
    """
    if not vault_crypto.is_valid_secret_name(name):
        raise InvalidSecretNameError(name)
    request_id = _id("vrq")
    now = _now()
    existing_name = _find_secret_name_case_insensitive(conn, name)
    if existing_name is not None and existing_name != name:
        raise SecretNameCaseConflictError(name, existing_name)
    already = existing_name == name
    pending_name = _find_pending_provision_name_case_insensitive(conn, name)
    if pending_name is not None and pending_name != name:
        raise SecretNameCaseConflictError(name, pending_name)
    status = "fulfilled" if already else "pending"
    normalized_spec = normalize_provision_spec(spec)
    context = resolve_resource_access_context(user_context)
    requester_payload = dict(requester) if isinstance(requester, dict) else requester
    session_id = requester_payload.get("session_id") if isinstance(requester_payload, dict) else None
    _require_request_session_authority(conn, session_id, context)
    resolved_message_id = message_id
    if isinstance(requester_payload, dict) and not resolved_message_id:
        _, derived_turn_id = _active_session_turn_anchor(conn, session_id)
        if derived_turn_id and not str(requester_payload.get("turn_id") or "").strip():
            requester_payload["turn_id"] = derived_turn_id
    card = _secure_input_card(name, request_id=request_id, reason=reason, spec=normalized_spec, session_id=session_id)
    delivery_payload: dict[str, Any] = {"card": card}
    if reason:
        delivery_payload["reason"] = reason
    if normalized_spec:
        delivery_payload["spec"] = normalized_spec
    stored_requester = _requester_with_authorization(requester_payload, context)
    try:
        conn.execute(
            vault_requests.insert().values(
                id=request_id,
                request_type="provision",
                secret_name=name,
                requester=json.dumps(stored_requester) if stored_requester is not None else None,
                delivery=json.dumps(delivery_payload),
                status=status,
                message_id=resolved_message_id,
                created_at=now,
                decided_at=now if already else None,
            )
        )
    except IntegrityError as exc:
        pending_name = _find_pending_provision_name_case_insensitive(conn, name)
        if pending_name is not None and pending_name != name:
            raise SecretNameCaseConflictError(name, pending_name) from exc
        raise VaultServiceError("failed to create provision request") from exc
    audit(conn, "provision_requested", secret_name=name, requester=stored_requester, request_id=request_id)
    return {
        "id": request_id,
        "secret_name": name,
        "status": status,
        "created_at": now,
        "card": card,
    }


def fulfill_provision(
    conn: Connection,
    request_id: str,
    sealed: Sealed,
    *,
    description: str | None = None,
) -> dict[str, Any]:
    """Store the caller-sealed value for a pending provision request."""
    row = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().first()
    if row is None:
        raise RequestNotFoundError(request_id)
    meta = create_secret(
        conn,
        name=row["secret_name"],
        sealed=sealed,
        description=description,
        provision_request_id=request_id,
    )
    return meta


def _secure_input_card(
    name: str,
    *,
    request_id: str,
    reason: str | None = None,
    spec: dict[str, Any] | None = None,
    session_id: str | None = None,
) -> dict[str, Any]:
    normalized_spec = normalize_provision_spec(spec)
    card = {
        "card_type": "secure_input",
        "request_id": request_id,
        "secret_name": name,
        # Carry the requesting session so surfaces can scope the card to its chat
        # (mirrors approval_card); UI reads resolve it into a display/link summary.
        "session_id": session_id,
        "reason": reason,
        "protection_options": ["standard", "protected"],
        "default_protection": normalized_spec.get("protection") or "protected",
        "value": None,
    }
    if normalized_spec:
        card["spec"] = normalized_spec
    return card


def _source_selector_payload(source_selector: dict[str, Any] | None = None) -> dict[str, Any]:
    if source_selector is None:
        return {"env": [], "tags": []}
    if not isinstance(source_selector, dict):
        raise InvalidGrantError("source_selector must be an object")
    env = _string_list(source_selector.get("env"), field="source_selector.env") if "env" in source_selector else []
    tags = _string_list(source_selector.get("tags"), field="source_selector.tags") if "tags" in source_selector else []
    skills = _string_list(source_selector.get("skills"), field="source_selector.skills") if "skills" in source_selector else []
    normalized_tags = _normalize_tags(tags)
    normalized_tags = list(dict.fromkeys([*normalized_tags, *(skill_tag(skill) for skill in skills)]))
    payload: dict[str, Any] = {}
    if env:
        payload["env"] = env
    if normalized_tags:
        payload["tags"] = normalized_tags
    return payload or {"env": [], "tags": []}


def _parse_env_selector(spec: str) -> tuple[str, str]:
    raw = spec.strip()
    if not raw:
        raise InvalidRequestError("env selector must be non-empty")
    if "=" in raw:
        env_name, record_ref = raw.split("=", 1)
        env_name = env_name.strip()
        record_ref = record_ref.strip()
        if not env_name:
            raise InvalidRequestError("env selector alias must be non-empty")
    else:
        record_ref = raw
        base, separator, field = record_ref.partition(".")
        env_name = base if not separator else f"{base}_{field.upper()}"
    if not _is_delivery_env_name(env_name):
        raise InvalidRequestError("env selector must use a valid env alias and secret name")
    if not vault_crypto.is_valid_secret_name(record_ref.split(".", 1)[0]):
        raise InvalidRequestError("env selector must use a valid env alias and secret name")
    return env_name, record_ref


def _is_delivery_env_name(name: str) -> bool:
    if not name or not name[0].isascii() or not (name[0].isalpha() or name[0] == "_"):
        return False
    return all(char.isascii() and (char.isalnum() or char == "_") for char in name)


def expand_value_delivery_selector(
    conn: Connection,
    *,
    env: list[str] | None = None,
    tags: list[str] | None = None,
    skills: list[str] | None = None,
    source_selector: dict[str, Any] | None = None,
    user_context: Any = None,
) -> dict[str, Any]:
    selector = _source_selector_payload(source_selector or {"env": env or [], "tags": tags or [], "skills": skills or []})
    context = resolve_resource_access_context(user_context)
    selections: list[dict[str, Any]] = []
    env_by_record: dict[str, str] = {}
    record_by_env: dict[str, str] = {}

    def add_selection(row: dict[str, Any], entry: dict[str, Any], env_name: str) -> None:
        _require_secret_resource_access(conn, row, context)
        secret_name = str(row["name"])
        _reject_keypair_value_delivery(row, secret_name)
        record = str(entry["name"])
        existing_env = env_by_record.get(record)
        if existing_env is not None:
            if existing_env != env_name:
                raise InvalidRequestError(f"{record} was selected with conflicting env names")
            return
        existing_record = record_by_env.get(env_name)
        if existing_record is not None and existing_record != record:
            raise InvalidRequestError(f"env {env_name} maps to multiple vault records")
        env_by_record[record] = env_name
        record_by_env[env_name] = record
        selections.append(
            {
                "name": secret_name,
                "field": str(entry["field"]),
                "record": record,
                "env": env_name,
                "kind": row.get("kind"),
                "protection": row.get("protection"),
            }
        )

    for env_spec in selector.get("env") or []:
        env_name, record_ref = _parse_env_selector(str(env_spec))
        row, entry = _resolve_record_ref(conn, record_ref, user_context=context)
        add_selection(row, entry, env_name)

    for tag in selector.get("tags") or []:
        normalized = _normalize_tag(str(tag))
        rows = [
            dict(row)
            for row in conn.execute(select(vault_secrets).order_by(vault_secrets.c.name)).mappings()
            if normalized in _row_tags(dict(row))
        ]
        for row in rows:
            _require_secret_resource_access(conn, row, context)
            for entry in _record_entries(row, strict=True):
                field = str(entry["field"])
                env_name = str(row["name"]) if entry["name"] == row["name"] else f"{row['name']}_{field.upper()}"
                add_selection(row, entry, env_name)

    return {"source_selector": selector, "secrets": selections}


def _request_member_rows_for_selector(
    conn: Connection,
    *,
    source_selector: dict[str, Any],
    user_context: Any = None,
) -> list[dict[str, Any]]:
    expanded = expand_value_delivery_selector(conn, source_selector=source_selector, user_context=user_context)
    rows: list[dict[str, Any]] = []
    seen_names: set[str] = set()
    for item in expanded["secrets"]:
        secret_name = str(item["name"])
        if secret_name in seen_names:
            continue
        seen_names.add(secret_name)
        row = _require_row(conn, secret_name)
        if row.get("protection") == "protected" or _secret_always_ask(row):
            rows.append(row)
    return rows


def _protected_delivery_names(delivery_payload: dict[str, Any]) -> list[str]:
    raw_names = delivery_payload.get("protected_secret_names")
    if not isinstance(raw_names, list):
        return []
    names: list[str] = []
    for raw_name in raw_names:
        if isinstance(raw_name, str) and raw_name:
            names.append(raw_name)
    return list(dict.fromkeys(names))


def _filter_request_rows_to_protected_names(
    rows: list[dict[str, Any]],
    protected_names: list[str],
) -> list[dict[str, Any]]:
    rows_by_name = {str(row["name"]): row for row in rows}
    filtered: list[dict[str, Any]] = []
    for name in protected_names:
        row = rows_by_name.get(name)
        if row is None:
            raise InvalidRequestError("protected_secret_names must be selected by source_selector")
        if row.get("protection") != "protected":
            raise InvalidRequestError("protected_secret_names must name protected secrets")
        filtered.append(row)
    return filtered


def _member_rows_for_names(
    conn: Connection,
    member_names: list[str],
    *,
    user_context: Any = None,
) -> list[dict[str, Any]]:
    context = resolve_resource_access_context(user_context)
    rows: list[dict[str, Any]] = []
    for name in member_names:
        row = _require_secret_resource_access(conn, _require_row(conn, str(name)), context)
        _reject_keypair_value_delivery(row, str(name))
        rows.append(row)
    return rows


def grantable_member_metas(
    conn: Connection,
    member_names: list[str],
    *,
    user_context: Any = None,
) -> list[dict[str, Any]]:
    return [
        _meta_payload(row)
        for row in _member_rows_for_names(conn, member_names, user_context=user_context)
        if _secret_access_grantable(row)
    ]


def request_grantable_member_metas(
    conn: Connection,
    request_id: str,
    *,
    user_context: Any = None,
) -> list[dict[str, Any]]:
    row = _load_request_for_transition(
        conn,
        str(request_id),
        request_type="access",
        allowed_statuses={"pending"},
        wrong_type_message="grant approval must complete an access request",
        wrong_status_message="grant approval request is not pending",
        expired_message="grant approval request has expired",
    )
    option = _request_grant_option(row)
    rows = _member_rows_for_names(conn, option.members, user_context=user_context)
    return [_meta_payload(row) for row in rows]


def _grant_option(
    conn: Connection,
    rows: list[dict[str, Any]],
    *,
    source_selector: dict[str, Any],
    purpose: str,
    one_shot: bool,
) -> dict[str, Any]:
    members = [str(row["name"]) for row in rows]
    settings = get_vault_settings(conn)
    default_duration = GRANT_DURATION_ONE_TIME if one_shot else settings["last_grant_ttl"]
    normalized_default_duration = normalize_grant_duration(default_duration)
    option = {
        "grant_id": _id("vgr"),
        "source_selector": source_selector,
        "purpose": purpose,
        "default_grant_duration": normalized_default_duration["last_grant_ttl"],
        "grant_duration_options": list(LAST_GRANT_TTL_OPTIONS),
        "default_ttl_seconds": normalized_default_duration["ttl_seconds"],
        "ttl_options_seconds": list(GRANT_TTL_OPTIONS_SECONDS),
        "session_binding_default": True,
        "member_count": len(members),
        "member_snapshot": members,
        "member_versions": [_member_version(row) for row in rows],
        "member_fields": [_field_metadata(row) for row in rows],
    }
    if one_shot:
        option["one_shot"] = True
    return option


def approval_card(
    conn: Connection,
    secret_name: str | None,
    *,
    request_id: str,
    request_type: str = "access",
    member_rows: list[dict[str, Any]] | None = None,
    source_selector: dict[str, Any] | None = None,
    purpose: str = "run",
    command: str | None = None,
    egress: str | None = None,
    skill: str | None = None,
    session_id: str | None = None,
    one_shot: bool = False,
    grantable: bool = True,
) -> dict[str, Any]:
    rows = member_rows if member_rows is not None else ([_require_row(conn, secret_name)] if secret_name else [])
    default_selector = {"env": [secret_name]} if secret_name else None
    selector = _source_selector_payload(source_selector or default_selector)
    grant_options = [_grant_option(conn, rows, source_selector=selector, purpose=purpose, one_shot=one_shot)] if grantable and rows else []
    protected_names = [str(row["name"]) for row in rows if row.get("protection") == "protected"]
    card = {
        "card_type": "approval",
        "request_id": request_id,
        "request_type": request_type,
        "secret_name": secret_name,
        "secret_names": [str(row["name"]) for row in rows],
        "protected_secret_names": protected_names,
        "source_selector": selector,
        "purpose": purpose,
        "command": command,
        "egress": egress,
        "skill": skill,
        "session_id": session_id,
        "approve_once": True,
        "one_shot": one_shot,
        "grant_options": grant_options,
        "value": None,
    }
    if len(rows) == 1:
        card["kind"] = rows[0].get("kind")
        card["protection"] = rows[0].get("protection")
    return card


def create_access_request(
    conn: Connection,
    name: str | None = None,
    *,
    source_selector: dict[str, Any] | None = None,
    purpose: str = "run",
    requester: Any = None,
    delivery: dict[str, Any] | None = None,
    message_id: str | None = None,
    expires_at: str | None = None,
    audience: str | None = None,
    user_context: Any = None,
) -> dict[str, Any]:
    if purpose not in GRANT_PURPOSES:
        raise InvalidRequestError(f"invalid grant purpose: {purpose!r}")
    context = resolve_resource_access_context(user_context)
    payload_audience = audience or _request_audience_from_requester(requester)
    delivery_payload = dict(delivery or {})
    requester_payload = requester if isinstance(requester, dict) else {}
    _require_request_session_authority(
        conn,
        requester_payload.get("session_id") or delivery_payload.get("session_id"),
        context,
    )
    default_selector = {"env": [name]} if name else None
    selector = _source_selector_payload(source_selector or default_selector)
    rows = _request_member_rows_for_selector(conn, source_selector=selector, user_context=context)
    protected_delivery_names = _protected_delivery_names(delivery_payload)
    if protected_delivery_names:
        rows = _filter_request_rows_to_protected_names(rows, protected_delivery_names)
    if name:
        direct_row, _entry = _resolve_record_ref(conn, name, user_context=context)
        name = str(direct_row["name"])
        if not _secret_access_requestable(direct_row):
            raise NotGrantableError(f"{name} is not access-requestable")
    if not rows:
        raise NotGrantableError("selector has no protected or approval-required static secrets")
    request_id = _id("vrq")
    if len(rows) == 1 and _secret_always_ask(rows[0]) and rows[0].get("protection") == "standard":
        one_shot = True
    else:
        one_shot = any(_secret_always_ask(row) for row in rows)
    card = approval_card(
        conn,
        str(rows[0]["name"]) if len(rows) == 1 else name,
        request_id=request_id,
        request_type="access",
        member_rows=rows,
        source_selector=selector,
        purpose=purpose,
        command=delivery_payload.get("command"),
        egress=delivery_payload.get("egress"),
        skill=delivery_payload.get("skill") or requester_payload.get("skill"),
        session_id=requester_payload.get("session_id") or delivery_payload.get("session_id"),
        one_shot=one_shot,
    )
    delivery_payload["card"] = card
    delivery_payload["source_selector"] = selector
    delivery_payload["purpose"] = purpose
    stored_requester = _requester_with_authorization(requester, context)
    conn.execute(
        vault_requests.insert().values(
            id=request_id,
            request_type="access",
            secret_name=str(rows[0]["name"]) if len(rows) == 1 else None,
            requester=json.dumps(stored_requester) if stored_requester is not None else None,
            delivery=json.dumps(delivery_payload),
            status="pending",
            message_id=message_id,
            created_at=_now(),
            expires_at=expires_at or _request_expiry(),
        )
    )
    audit(
        conn,
        "access_requested",
        secret_name=name,
        requester=stored_requester,
        delivery=delivery_payload,
        request_id=request_id,
    )
    row = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(row), conn=conn, audience=payload_audience)


def create_sign_request(
    conn: Connection,
    name: str,
    *,
    digest: str,
    scheme: str,
    signing_context: dict[str, Any] | None = None,
    requester: Any = None,
    delivery: dict[str, Any] | None = None,
    message_id: str | None = None,
    expires_at: str | None = None,
    user_context: Any = None,
) -> dict[str, Any]:
    if scheme not in SUPPORTED_SIGNATURE_SCHEMES:
        raise InvalidRequestError(f"unsupported signature scheme: {scheme}")
    context = resolve_resource_access_context(user_context)
    row = _require_secret_resource_access(conn, _require_row(conn, name), context)
    if row.get("kind") != "keypair":
        raise InvalidRequestError(f"{name} is not a signing key")
    if row.get("signer_kind") not in (None, "local"):
        raise InvalidRequestError(f"{name} is not locally signable")
    _reject_unsignable_keypair(row, name)
    payload_audience = _request_audience_from_requester(requester)
    request_id = _id("vrq")
    delivery_payload = dict(delivery or {})
    requester_payload = requester if isinstance(requester, dict) else {}
    _require_request_session_authority(
        conn,
        requester_payload.get("session_id") or delivery_payload.get("session_id"),
        context,
    )
    card = approval_card(
        conn,
        name,
        request_id=request_id,
        request_type="sign",
        command=delivery_payload.get("command") or f"sign:{scheme}",
        egress=delivery_payload.get("egress") or "signature",
        skill=delivery_payload.get("skill") or requester_payload.get("skill"),
        session_id=requester_payload.get("session_id") or delivery_payload.get("session_id"),
        grantable=False,
    )
    delivery_payload.update({"digest": digest, "scheme": scheme, "card": card})
    if signing_context is not None:
        delivery_payload["signing_context"] = signing_context
    stored_requester = _requester_with_authorization(requester, context)
    conn.execute(
        vault_requests.insert().values(
            id=request_id,
            request_type="sign",
            secret_name=name,
            requester=json.dumps(stored_requester) if stored_requester is not None else None,
            delivery=json.dumps(delivery_payload),
            status="pending",
            message_id=message_id,
            created_at=_now(),
            expires_at=expires_at or _request_expiry(),
        )
    )
    audit(
        conn,
        "sign_requested",
        secret_name=name,
        requester=stored_requester,
        delivery=delivery_payload,
        request_id=request_id,
    )
    row = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(row), conn=conn, audience=payload_audience)


def create_delete_request(
    conn: Connection,
    name: str,
    *,
    reason: str | None = None,
    requester: Any = None,
    message_id: str | None = None,
    user_context: Any = None,
    return_created: bool = False,
) -> dict[str, Any] | tuple[dict[str, Any], bool]:
    """Ask for deletion without accessing any secret value or unlock material."""
    context = resolve_resource_access_context(user_context)
    # Acquire SQLite's writer reservation before lookup/dedupe. A no-op write
    # serializes simultaneous asks with deletion without changing the envelope.
    conn.execute(
        vault_secrets.update().where(vault_secrets.c.name == name)
        .values(updated_at=vault_secrets.c.updated_at)
    )
    secret = _require_secret_resource_access(conn, _require_row(conn, name), context)
    requester_payload = requester if isinstance(requester, dict) else {}
    session_id = requester_payload.get("session_id")
    _require_request_session_authority(conn, session_id, context)
    audience = _request_audience_from_requester(requester)
    pending_rows = conn.execute(
        select(vault_requests).where(
            vault_requests.c.request_type == "delete",
            vault_requests.c.secret_name == name,
            vault_requests.c.status == "pending",
        )
    ).mappings().all()
    for pending in pending_rows:
        existing, _ = _expire_request_if_due(conn, dict(pending))
        if existing["status"] == "pending":
            payload = _request_row_payload(existing, conn=conn, audience=audience)
            return (payload, False) if return_created else payload
    request_id = _id("vrq")
    card = {
        "card_type": "approval",
        "request_type": "delete",
        "secret_name": name,
        "kind": secret.get("kind"),
        "protection": secret.get("protection"),
        "description": _public_meta(secret.get("public_meta")).get("description"),
        "tags": _row_tags(secret),
        "session_id": session_id,
        "reason": reason,
        **_field_metadata(secret),
    }
    delivery = {"reason": reason, "card": card}
    stored_requester = _requester_with_authorization(requester, context)
    conn.execute(
        vault_requests.insert().values(
            id=request_id,
            request_type="delete",
            secret_name=name,
            requester=json.dumps(stored_requester) if stored_requester is not None else None,
            delivery=json.dumps(delivery),
            status="pending",
            message_id=message_id,
            created_at=_now(),
            expires_at=_request_expiry(),
        )
    )
    audit(conn, "delete_requested", secret_name=name, requester=stored_requester, delivery=delivery, request_id=request_id)
    row = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    payload = _request_row_payload(dict(row), conn=conn, audience=audience)
    return (payload, True) if return_created else payload


def approve_delete_request(
    conn: Connection,
    request_id: str,
    *,
    release_scopes: list[dict[str, str]] | None = None,
    user_context: Any = None,
) -> dict[str, Any]:
    """Atomically decide and delete; release collected avault scopes after commit."""
    row = _load_request_for_transition(
        conn,
        request_id,
        request_type="delete",
        allowed_statuses={"pending"},
        wrong_type_message="delete approval must target a delete request",
        wrong_status_message="delete request is not pending",
        expired_message="delete request has expired",
    )
    name = str(row["secret_name"])
    context = resolve_resource_access_context(user_context)
    _require_secret_resource_management(conn, _require_row(conn, name), context)
    claim = conn.execute(
        vault_requests.update()
        .where(vault_requests.c.id == request_id, vault_requests.c.status == "pending")
        .values(status="approved", decided_at=_now(), callback_status="pending")
    )
    if claim.rowcount != 1:
        raise InvalidRequestError("delete request is not pending")
    grant_rows = active_grant_rows_for_secret(conn, name)
    delete_secret(conn, name, user_context=context)
    scopes = agent_release_scopes_after_rows(conn, grant_rows)
    if release_scopes is not None:
        release_scopes.extend(scopes)
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(updated), conn=conn, audience=REQUEST_AUDIENCE_AGENT)


def _signature_bytes(raw: str) -> bytes:
    try:
        return bytes.fromhex(raw)
    except ValueError as exc:
        raise InvalidRequestError("signature must be hex-encoded bytes") from exc


def _validate_signature_payload(scheme: str, signature: dict[str, Any]) -> None:
    if scheme not in SUPPORTED_SIGNATURE_SCHEMES:
        raise InvalidRequestError(f"unsupported signature scheme: {scheme}")
    if not isinstance(signature, dict):
        raise InvalidRequestError("signature payload must be an object")
    sig = signature.get("signature")
    if not isinstance(sig, str) or not sig:
        raise InvalidRequestError("signature payload requires a non-empty signature")
    sig_bytes = _signature_bytes(sig)
    recovery_id = signature.get("recovery_id")
    if scheme == "ecdsa-secp256k1-recoverable":
        if len(sig_bytes) != 64:
            raise InvalidRequestError("recoverable secp256k1 signatures must be 64 bytes")
        if type(recovery_id) is not int or recovery_id not in {0, 1, 2, 3}:
            raise InvalidRequestError("recoverable secp256k1 signatures require recovery_id 0..3")
        return
    if scheme == "ecdsa-secp256k1-der":
        if len(sig_bytes) < 8 or sig_bytes[0] != 0x30:
            raise InvalidRequestError("DER secp256k1 signatures must be DER-encoded")
        if recovery_id is not None:
            raise InvalidRequestError("DER secp256k1 signatures must not include recovery_id")
        return
    if scheme == "schnorr-secp256k1-bip340":
        if len(sig_bytes) != 64:
            raise InvalidRequestError("BIP340 Schnorr signatures must be 64 bytes")
        if recovery_id is not None:
            raise InvalidRequestError("BIP340 Schnorr signatures must not include recovery_id")
        return

def complete_sign_request(
    conn: Connection,
    request_id: str,
    *,
    name: str,
    digest: str,
    scheme: str,
    signature: dict[str, Any],
    requester: Any = None,
    browser_signed: bool = False,
) -> dict[str, Any]:
    row_dict = _load_request_for_transition(
        conn,
        request_id,
        request_type="sign",
        allowed_statuses={"pending", "signing"},
        wrong_type_message="signature completion must target a sign request",
        wrong_status_message="sign request is not pending",
        expired_message="sign request has expired",
    )
    if row_dict.get("secret_name") != name:
        raise InvalidRequestError("signature secret does not match the sign request")
    _, delivery = _request_json_payloads(row_dict)
    delivery_payload = delivery if isinstance(delivery, dict) else {}
    if delivery_payload.get("digest") != digest or delivery_payload.get("scheme") != scheme:
        raise InvalidRequestError("signature payload does not match the sign request")
    _validate_signature_payload(scheme, signature)
    completed_delivery = dict(delivery_payload)
    completed_delivery["signature"] = signature
    claim = conn.execute(
        vault_requests.update()
        .where(vault_requests.c.id == request_id, vault_requests.c.request_type == "sign", vault_requests.c.status == row_dict["status"])
        .values(status="approved", decided_at=_now(), delivery=json.dumps(completed_delivery), callback_status="pending")
    )
    if claim.rowcount != 1:
        raise InvalidRequestError("sign request is not pending")
    record_signing_use(
        conn,
        name,
        requester=requester,
        delivery={"scheme": scheme, "digest": digest, "browser_signed": bool(browser_signed)},
        request_id=request_id,
    )
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(updated), conn=conn, audience=REQUEST_AUDIENCE_AGENT)


def get_request(
    conn: Connection,
    request_id: str,
    *,
    audience: str | None = REQUEST_AUDIENCE_UI,
    user_context: Any = None,
) -> dict[str, Any]:
    row_dict = _load_request_row(conn, request_id)
    _require_request_secret_access(conn, row_dict, user_context=user_context)
    return _request_row_payload(row_dict, conn=conn, audience=audience)


def set_request_operation_context(
    conn: Connection,
    request_id: str,
    operation_context: dict[str, Any],
    *,
    audience: str | None = REQUEST_AUDIENCE_UI,
) -> dict[str, Any]:
    row_dict = _load_request_row(conn, request_id)
    _, delivery = _request_json_payloads(row_dict)
    delivery_payload = dict(delivery) if isinstance(delivery, dict) else {}
    delivery_payload["operation_context"] = operation_context
    card = delivery_payload.get("card")
    if isinstance(card, dict):
        next_card = dict(card)
        next_card["operation_context"] = operation_context
        delivery_payload["card"] = next_card
    conn.execute(
        vault_requests.update()
        .where(vault_requests.c.id == request_id)
        .values(delivery=json.dumps(delivery_payload))
    )
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(updated), conn=conn, audience=audience)


def _agent_binding_record_item_names(record: dict[str, Any]) -> set[str]:
    items = record.get("items")
    if not isinstance(items, list):
        return set()
    return {str(item.get("name") or "") for item in items if isinstance(item, dict) and item.get("name")}


def _agent_binding_record_superseded(existing_record: dict[str, Any], new_record: dict[str, Any]) -> bool:
    existing_names = _agent_binding_record_item_names(existing_record)
    new_names = _agent_binding_record_item_names(new_record)
    if not existing_names or not new_names:
        return False
    existing_grant_id = str(existing_record.get("grant_id") or "")
    new_grant_id = str(new_record.get("grant_id") or "")
    if existing_grant_id and new_grant_id and existing_grant_id != new_grant_id:
        return False
    return existing_names.issubset(new_names)


def _agent_binding_approval_record_cap(row_dict: dict[str, Any], new_record: dict[str, Any]) -> int:
    _, delivery = _request_json_payloads(row_dict)
    delivery_payload = delivery if isinstance(delivery, dict) else {}
    card = delivery_payload.get("card") if isinstance(delivery_payload.get("card"), dict) else {}
    grant_options = card.get("grant_options") if isinstance(card, dict) else []
    member_count = 0
    if isinstance(grant_options, list):
        for option in grant_options:
            if not isinstance(option, dict):
                continue
            members = option.get("member_snapshot")
            if isinstance(members, list):
                member_count = max(member_count, len([name for name in members if isinstance(name, str) and name]))
            member_fields = option.get("member_fields")
            if isinstance(member_fields, list):
                member_count = max(
                    member_count,
                    sum(len(secret_record_names(meta)) for meta in member_fields if isinstance(meta, dict)),
                )
    return max(1, member_count, len(_agent_binding_record_item_names(new_record)))


def record_request_agent_binding_approvals(
    conn: Connection,
    request_id: str,
    record: dict[str, Any],
    *,
    max_records: int | None = None,
) -> dict[str, Any]:
    if not isinstance(record, dict):
        raise InvalidRequestError("agent binding approval record must be an object")
    row_dict = _load_request_row(conn, request_id)
    _, delivery = _request_json_payloads(row_dict)
    delivery_payload = dict(delivery) if isinstance(delivery, dict) else {}
    records = delivery_payload.get("agent_binding_approvals")
    if not isinstance(records, list):
        records = []
    records = [
        existing
        for existing in records
        if isinstance(existing, dict) and not _agent_binding_record_superseded(existing, record)
    ]
    records.append(record)
    if max_records is not None:
        records = records[-max(1, max_records) :]
    else:
        records = records[-_agent_binding_approval_record_cap(row_dict, record) :]
    delivery_payload["agent_binding_approvals"] = records
    conn.execute(
        vault_requests.update()
        .where(vault_requests.c.id == request_id)
        .values(delivery=json.dumps(delivery_payload))
    )
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(updated), conn=conn, audience=REQUEST_AUDIENCE_AGENT)


def claim_sign_request(
    conn: Connection,
    request_id: str,
    *,
    name: str,
    digest: str,
    scheme: str,
) -> dict[str, Any]:
    row_dict = _load_request_for_transition(
        conn,
        request_id,
        request_type="sign",
        allowed_statuses={"pending"},
        wrong_type_message="signature completion must target a sign request",
        wrong_status_message="sign request is not pending",
        expired_message="sign request has expired",
    )
    if row_dict.get("secret_name") != name:
        raise InvalidRequestError("signature secret does not match the sign request")
    _, delivery = _request_json_payloads(row_dict)
    delivery_payload = delivery if isinstance(delivery, dict) else {}
    if delivery_payload.get("digest") != digest or delivery_payload.get("scheme") != scheme:
        raise InvalidRequestError("signature payload does not match the sign request")
    claim = conn.execute(
        vault_requests.update()
        .where(vault_requests.c.id == request_id, vault_requests.c.request_type == "sign", vault_requests.c.status == "pending")
        .values(status="signing", decided_at=_now())
    )
    if claim.rowcount != 1:
        raise InvalidRequestError("sign request is not pending")
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(updated), conn=conn, audience=REQUEST_AUDIENCE_AGENT)


def release_sign_request_claim(conn: Connection, request_id: str) -> dict[str, Any]:
    """Return a claimed sign request to pending because avault signed nothing.

    Only for a failure before signing that the user can fix and approve again,
    such as avault's one-time Keychain authorization: the claim existed to stop
    a second signature, and there was no first one.
    """
    result = conn.execute(
        vault_requests.update()
        .where(vault_requests.c.id == request_id, vault_requests.c.request_type == "sign", vault_requests.c.status == "signing")
        .values(status="pending", decided_at=None)
    )
    if result.rowcount != 1:
        raise InvalidRequestError("sign request is not signing")
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(updated), conn=conn, audience=REQUEST_AUDIENCE_AGENT)


def fail_sign_request(conn: Connection, request_id: str, *, reason: str | None = None) -> dict[str, Any]:
    row_dict = _load_request_for_transition(
        conn,
        request_id,
        request_type="sign",
        allowed_statuses={"signing"},
        wrong_type_message="signature completion must target a sign request",
        wrong_status_message="sign request is not signing",
        expired_message="sign request has expired",
    )
    _, delivery = _request_json_payloads(row_dict)
    delivery_payload = dict(delivery) if isinstance(delivery, dict) else {}
    failure_payload: dict[str, Any] = {"request_type": "sign"}
    if reason:
        failure_payload["reason"] = reason
    delivery_payload["failure"] = failure_payload
    result = conn.execute(
        vault_requests.update()
        .where(vault_requests.c.id == request_id, vault_requests.c.status == "signing")
        .values(status="failed", decided_at=_now(), delivery=json.dumps(delivery_payload), callback_status="pending")
    )
    if result.rowcount != 1:
        raise InvalidRequestError("sign request is not signing")
    audit(
        conn,
        "request-failed",
        secret_name=row_dict.get("secret_name"),
        delivery=failure_payload,
        request_id=request_id,
    )
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(updated), conn=conn, audience=REQUEST_AUDIENCE_AGENT)


def validate_sign_request(
    conn: Connection,
    request_id: str,
    *,
    name: str,
    digest: str,
    scheme: str,
) -> dict[str, Any]:
    row_dict = _load_request_for_transition(
        conn,
        request_id,
        request_type="sign",
        allowed_statuses={"pending"},
        wrong_type_message="signature completion must target a sign request",
        wrong_status_message="sign request is not pending",
        expired_message="sign request has expired",
    )
    if row_dict.get("secret_name") != name:
        raise InvalidRequestError("signature secret does not match the sign request")
    _, delivery = _request_json_payloads(row_dict)
    delivery_payload = delivery if isinstance(delivery, dict) else {}
    if delivery_payload.get("digest") != digest or delivery_payload.get("scheme") != scheme:
        raise InvalidRequestError("signature payload does not match the sign request")
    return _request_row_payload(row_dict, conn=conn, audience=REQUEST_AUDIENCE_AGENT)


def deny_request(
    conn: Connection,
    request_id: str,
    *,
    requester: Any = None,
    reason: str | None = None,
    user_context: Any = None,
) -> dict[str, Any]:
    request_row = _load_request_row(conn, request_id)
    _require_request_secret_access(conn, request_row, user_context=user_context, management=True)
    row_dict = _load_request_for_transition(
        conn,
        request_id,
        request_type=None,
        allowed_statuses={"pending"},
        wrong_type_message="request is invalid",
        wrong_status_message="request is not pending",
        expired_message="request has expired",
    )
    decided_at = _now()
    result = conn.execute(
        vault_requests.update()
        .where(vault_requests.c.id == request_id, vault_requests.c.status == "pending")
        .values(status="denied", decided_at=decided_at, callback_status="pending")
    )
    if result.rowcount != 1:
        raise InvalidRequestError("request is not pending")
    delivery: dict[str, Any] = {"request_type": row_dict.get("request_type")}
    if reason:
        delivery["reason"] = reason
    audit(
        conn,
        "request-denied",
        secret_name=row_dict.get("secret_name"),
        requester=requester,
        delivery=delivery,
        request_id=request_id,
    )
    updated = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().one()
    return _request_row_payload(dict(updated), conn=conn, audience=REQUEST_AUDIENCE_AGENT)


def list_requests(
    conn: Connection,
    *,
    status: str | None = "pending",
    request_type: str | None = None,
    limit: int = 100,
    session: str | None = None,
    user_context: Any = None,
) -> list[dict[str, Any]]:
    _expire_pending_requests(conn)
    context = resolve_resource_access_context(user_context)
    query = select(vault_requests).order_by(vault_requests.c.created_at.desc(), vault_requests.c.id.desc())
    if status is not None:
        query = query.where(vault_requests.c.status == status)
    if request_type is not None:
        query = query.where(vault_requests.c.request_type == request_type)
    # Session and remote ACL filters run in Python, so apply the limit only after
    # those filters or newer inaccessible rows could hide older visible requests.
    has_full_runtime_access = context.has_role("editor")
    requires_post_filter = session is not None or not has_full_runtime_access
    if not requires_post_filter:
        query = query.limit(limit)
    rows = [dict(row) for row in conn.execute(query).mappings()]
    if session is not None:
        rows = [row for row in rows if _request_session_id(row) == session]
    if not has_full_runtime_access:
        accessible_rows: list[dict[str, Any]] = []
        for row in rows:
            try:
                _require_request_secret_access(conn, row, user_context=context)
            except VaultSecretAccessError:
                continue
            accessible_rows.append(row)
        rows = accessible_rows
    if requires_post_filter:
        rows = rows[:limit]
    return [_request_row_payload(row, conn=conn, audience=REQUEST_AUDIENCE_UI) for row in rows]


def resolve_pending_provision_request_by_name(
    conn: Connection,
    name: str,
    *,
    user_context: Any = None,
) -> tuple[dict[str, Any] | None, bool]:
    _expire_pending_requests(conn)
    rows = list(
        conn.execute(
            select(vault_requests)
            .where(
                vault_requests.c.status == "pending",
                vault_requests.c.request_type == "provision",
                vault_requests.c.secret_name == name,
            )
            .order_by(vault_requests.c.created_at.desc(), vault_requests.c.id.desc())
            .limit(2)
        ).mappings()
    )
    row_dicts = [dict(row) for row in rows]
    for row in row_dicts:
        _require_request_secret_access(conn, row, user_context=user_context)
    if len(row_dicts) == 1:
        return _request_row_payload(row_dicts[0], conn=conn, audience=REQUEST_AUDIENCE_UI), False
    return None, len(rows) > 1


def find_pending_provision_request(conn: Connection, name: str) -> dict[str, Any] | None:
    request, _ambiguous = resolve_pending_provision_request_by_name(conn, name)
    return request


def get_pending_provision_request(
    conn: Connection,
    request_id: str,
    *,
    user_context: Any = None,
) -> dict[str, Any] | None:
    _expire_pending_requests(conn)
    row = (
        conn.execute(
            select(vault_requests)
            .where(
                vault_requests.c.id == request_id,
                vault_requests.c.status == "pending",
                vault_requests.c.request_type == "provision",
            )
            .limit(1)
        )
        .mappings()
        .first()
    )
    if row is None:
        return None
    row_dict = dict(row)
    _require_request_secret_access(conn, row_dict, user_context=user_context)
    return _request_row_payload(row_dict, conn=conn, audience=REQUEST_AUDIENCE_UI)


def _expire_grant_rows(
    conn: Connection,
    rows: list[dict[str, Any]],
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    reason: str = "grant-expired",
) -> int:
    now = _now()
    expired = 0
    for row in rows:
        conn.execute(
            vault_grants.update()
            .where(vault_grants.c.id == row["id"], vault_grants.c.status.in_(ACTIVE_GRANT_STATES))
            .values(status="expired", revoked_at=now, agent_ready=0, agent_ready_at=None)
        )
        cache.drop(row["id"])
        audit(conn, reason, grant_id=row["id"], delivery={"grant_id": row["id"]})
        expired += 1
    return expired


def _expire_active_grants_for_secret(
    conn: Connection,
    secret_name: str,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    reason: str = "grant-expired",
) -> int:
    rows = active_grant_rows_for_secret(conn, secret_name)
    return _expire_grant_rows(conn, rows, cache=cache, reason=reason)


def active_grant_rows_for_secret(conn: Connection, secret_name: str) -> list[dict[str, Any]]:
    return [
        dict(row)
        for row in conn.execute(select(vault_grants).where(vault_grants.c.status.in_(ACTIVE_GRANT_STATES))).mappings()
        if secret_name in (_loads(row.get("member_snapshot")) or [])
    ]


def active_grant_scopes_for_secret(conn: Connection, secret_name: str) -> list[dict[str, str]]:
    return _unique_grant_release_refs(active_grant_rows_for_secret(conn, secret_name))


def active_grant_scopes_for_session(conn: Connection, session_id: str) -> list[dict[str, str]]:
    rows = [
        dict(row)
        for row in conn.execute(
            select(vault_grants).where(vault_grants.c.status.in_(ACTIVE_GRANT_STATES), vault_grants.c.session_id == session_id)
        ).mappings()
    ]
    return _unique_grant_release_refs(rows)


def agent_release_scopes_after_rows(
    conn: Connection,
    rows: list[dict[str, Any]],
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
) -> list[dict[str, str]]:
    """Return resident-agent grant ids that must be dropped after rows stop being active."""

    now = _now()
    expired_rows = [
        dict(row)
        for row in conn.execute(
            select(vault_grants).where(vault_grants.c.status.in_(ACTIVE_GRANT_STATES), vault_grants.c.expires_at <= now)
        ).mappings()
    ]
    if expired_rows:
        _expire_grant_rows(conn, expired_rows, cache=cache)
    rows = [*rows, *expired_rows]
    rows = [dict(row) for row in rows if grant_row_has_resident_agent_ready(dict(row))]
    if not rows:
        return []
    release_refs: list[dict[str, str]] = []
    for row in rows:
        grant_id = str(row.get("id") or "")
        if not grant_id:
            continue
        cache.drop(grant_id)
        _clear_grant_agent_ready(conn, grant_id)
        release_refs.append({"grant_id": grant_id})
    return release_refs


def expire_grant(
    conn: Connection,
    grant_id: str,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    reason: str = "grant-expired",
) -> dict[str, Any]:
    row = conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().first()
    if row is None:
        raise GrantNotFoundError(grant_id)
    row_dict = dict(row)
    if row_dict.get("status") in ACTIVE_GRANT_STATES:
        _expire_grant_rows(conn, [row_dict], cache=cache, reason=reason)
        row_dict = dict(conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().one())
    return _grant_payload(conn, row_dict, cache=cache)


def _expire_pending_requests_for_secret(
    conn: Connection,
    secret_name: str,
    *,
    reason: str = "request-expired",
) -> int:
    changed_members = {secret_name}
    rows = [
        dict(row)
        for row in conn.execute(
            select(vault_requests).where(
                vault_requests.c.status == "pending",
                vault_requests.c.request_type.in_(("access", "sign")),
            )
        ).mappings()
        if row.get("secret_name") == secret_name or _request_covers_any_member(dict(row), changed_members)
    ]
    if not rows:
        return 0
    return _expire_pending_request_rows(conn, rows, reason=reason, delivery_extra={"changed_secret": secret_name})


def expire_session_requests(conn: Connection, session_id: str, *, reason: str = "request-expired-session-archived") -> int:
    rows = [
        dict(row)
        for row in conn.execute(
            select(vault_requests).where(
                vault_requests.c.status == "pending",
                vault_requests.c.request_type.in_(("access", "sign", "delete")),
            )
        ).mappings()
        if _request_session_id(dict(row)) == session_id
    ]
    if not rows:
        return 0
    return _expire_pending_request_rows(conn, rows, reason=reason, delivery_extra={"session_id": session_id})


def expire_grants(conn: Connection, *, cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE) -> int:
    now = _now()
    rows = [
        dict(row)
        for row in conn.execute(
            select(vault_grants).where(vault_grants.c.status.in_(ACTIVE_GRANT_STATES), vault_grants.c.expires_at <= now)
        ).mappings()
    ]
    return _expire_grant_rows(conn, rows, cache=cache)


def _validate_access_request_for_grant(
    conn: Connection,
    request_id: str,
    *,
    session_id: str | None,
    inherit_request_session: bool,
    live_members: list[str],
    source_selector: dict[str, Any],
    purpose: str,
) -> GrantApproval:
    row_dict = _load_request_for_transition(
        conn,
        request_id,
        request_type="access",
        allowed_statuses={"pending"},
        wrong_type_message="grant approval must complete an access request",
        wrong_status_message="grant approval request is not pending",
        expired_message="grant approval request has expired",
    )
    requested_session_id = _request_session_id(row_dict)
    effective_session_id = requested_session_id if session_id is None and inherit_request_session else session_id
    option = _request_grant_option(row_dict)
    if option.one_shot and requested_session_id:
        effective_session_id = requested_session_id
    if requested_session_id and effective_session_id and requested_session_id != effective_session_id:
        raise InvalidRequestError("grant session does not match the approval request")
    if option.purpose != purpose:
        raise InvalidRequestError("grant purpose does not match the approval request")
    if option.source_selector != _source_selector_payload(source_selector):
        raise InvalidRequestError("grant source selector does not match the approval request")
    if set(option.members) != set(live_members):
        raise InvalidRequestError("grant approval snapshot has stale members")
    card = _request_card(row_dict)
    raw_options = card.get("grant_options") if isinstance(card, dict) else None
    raw_option = raw_options[0] if isinstance(raw_options, list) and raw_options and isinstance(raw_options[0], dict) else {}
    versions = raw_option.get("member_versions")
    if not isinstance(versions, list):
        raise InvalidRequestError("grant approval snapshot is stale")
    versions_by_name = {
        item.get("name"): item
        for item in versions
        if isinstance(item, dict) and isinstance(item.get("name"), str)
    }
    if set(versions_by_name) != set(option.members):
        raise InvalidRequestError("grant approval snapshot is stale")
    current_rows = {
        current["name"]: dict(current)
        for current in conn.execute(select(vault_secrets).where(vault_secrets.c.name.in_(option.members))).mappings()
    }
    for member_name in option.members:
        current = current_rows.get(member_name)
        if current is None or member_name not in live_members:
            raise InvalidRequestError("grant approval snapshot has stale members")
        if not _member_version_matches(current, versions_by_name[member_name]):
            raise InvalidRequestError("grant approval snapshot has stale members")
    return GrantApproval(
        grant_id=option.grant_id,
        members=option.members,
        session_id=effective_session_id,
        source_selector=option.source_selector,
        purpose=option.purpose,
        one_shot=option.one_shot,
        ttl_cap_seconds=option.ttl_cap_seconds,
    )


def _approve_sibling_access_requests_for_grant(
    conn: Connection,
    *,
    request_id: str,
    members: list[str],
    session_id: str | None,
    purpose: str,
    decided_at: str,
) -> int:
    if not members:
        return 0
    target_session_id = session_id
    if not target_session_id:
        approval_row = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().first()
        target_session_id = _request_session_id(dict(approval_row)) if approval_row else None
    if not target_session_id:
        return 0
    member_set = {str(name) for name in members if str(name)}

    def _same_purpose_subset(row: dict[str, Any]) -> bool:
        try:
            option = _request_grant_option(row)
        except InvalidRequestError:
            return False
        return option.purpose == purpose and _request_members_are_subset(row, member_set)

    rows = [
        dict(row)
        for row in conn.execute(
            select(vault_requests).where(
                vault_requests.c.id != request_id,
                vault_requests.c.request_type == "access",
                vault_requests.c.status == "pending",
            )
        ).mappings()
        if _request_session_id(dict(row)) == target_session_id and _same_purpose_subset(dict(row))
    ]
    approved = 0
    now_dt = datetime.now(timezone.utc)
    for row in rows:
        expires_at = _parse_iso_datetime(row.get("expires_at"))
        if expires_at is not None and expires_at <= now_dt:
            _expire_pending_request_rows(
                conn,
                [row],
                delivery_extra={"session_id": target_session_id},
            )
            continue
        result = conn.execute(
            vault_requests.update()
            .where(vault_requests.c.id == row["id"], vault_requests.c.status == "pending")
            .values(status="approved", decided_at=decided_at, callback_status="pending")
        )
        if result.rowcount != 1:
            continue
        audit(
            conn,
            "request-approved-by-grant",
            secret_name=row.get("secret_name"),
            delivery={"request_type": "access", "session_id": target_session_id},
            request_id=row["id"],
        )
        approved += 1
    return approved


def restore_access_request_after_failed_grant(
    conn: Connection,
    *,
    request_id: str,
    member_names: list[str] | set[str] | tuple[str, ...],
    session_id: str | None,
) -> int:
    """Make a protected grant approval retryable after resident-agent relay fails."""

    members = {str(name) for name in member_names if str(name)}
    if not request_id or not members:
        return 0
    approval_row = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().first()
    if approval_row is None or approval_row.get("status") != "approved":
        return 0
    decided_at = approval_row.get("decided_at")
    target_session_id = session_id or _request_session_id(dict(approval_row))
    rows = [
        dict(row)
        for row in conn.execute(
            select(vault_requests).where(
                vault_requests.c.request_type == "access",
                vault_requests.c.status == "approved",
            )
        ).mappings()
        if row["id"] == request_id
        or (
            _request_members_are_subset(dict(row), members)
            and target_session_id
            and row.get("decided_at") == decided_at
            and _request_session_id(dict(row)) == target_session_id
        )
    ]
    restored = 0
    for row in rows:
        result = conn.execute(
            vault_requests.update()
            .where(vault_requests.c.id == row["id"], vault_requests.c.status == "approved")
            .values(status="pending", decided_at=None, callback_status=None)
        )
        if result.rowcount != 1:
            continue
        audit(
            conn,
            "request-restored-after-grant-relay-failed",
            secret_name=row.get("secret_name"),
            delivery={"request_type": "access", "session_id": target_session_id},
            request_id=row["id"],
        )
        restored += 1
    return restored


def create_grant(
    conn: Connection,
    *,
    member_names: list[str],
    source_selector: dict[str, Any],
    purpose: str = "run",
    session_id: str | None = None,
    ttl_seconds: int | None = None,
    grant_duration: Any | None = None,
    expires_at: str | None = None,
    request_id: str | None = None,
    inherit_request_session: bool = True,
    expected_member_names: set[str] | list[str] | tuple[str, ...] | None = None,
    cache_ready: bool = True,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    user_context: Any = None,
) -> dict[str, Any]:
    if purpose not in GRANT_PURPOSES:
        raise InvalidGrantError(f"invalid grant purpose: {purpose!r}")
    if not request_id:
        raise InvalidRequestError("grant creation requires an approval request")
    context = resolve_resource_access_context(user_context)
    selector = _source_selector_payload(source_selector)
    live_rows = _member_rows_for_names(conn, member_names, user_context=context)
    live_members = [row["name"] for row in live_rows]
    if not live_members:
        raise NotGrantableError("grant has no static secrets")
    approval = _validate_access_request_for_grant(
        conn,
        request_id,
        session_id=session_id,
        inherit_request_session=inherit_request_session,
        live_members=live_members,
        source_selector=selector,
        purpose=purpose,
    )
    session_id = approval.session_id
    members = approval.members
    if any(name not in live_members for name in members):
        raise InvalidRequestError("grant approval snapshot has stale members")
    if expected_member_names is not None and set(members) != set(expected_member_names):
        raise InvalidGrantError("resident agent DEKs must match the approved grant members")
    live_rows_by_name = {row["name"]: row for row in live_rows}
    remember_duration = grant_duration is not None or ttl_seconds is not None
    default_duration = GRANT_DURATION_ONE_TIME if approval.one_shot else get_vault_settings(conn)["last_grant_ttl"]
    duration = normalize_grant_duration(grant_duration, default=default_duration)
    if ttl_seconds is not None:
        if grant_duration is not None:
            raise InvalidGrantError("use grant_duration or ttl_seconds, not both")
        duration = normalize_grant_duration(ttl_seconds)
    one_shot_grant = approval.one_shot or bool(duration["one_shot"])
    if one_shot_grant:
        requested_session_id = _request_session_id(_load_request_row(conn, request_id))
        if requested_session_id:
            if session_id and session_id != requested_session_id:
                raise InvalidRequestError("grant session does not match the approval request")
            session_id = requested_session_id
    resident_cache_ready = cache_ready and any(live_rows_by_name[name].get("protection") == "protected" for name in members)
    ttl = int(duration["ttl_seconds"])
    ttl = max(1, min(ttl, approval.ttl_cap_seconds))
    now_dt = datetime.now(timezone.utc)
    expires_at_dt = now_dt + timedelta(seconds=ttl)
    if expires_at is not None:
        issued_expires_at = _parse_iso_datetime(expires_at)
        if issued_expires_at is None:
            raise InvalidGrantError("grant binding expiry is invalid")
        if issued_expires_at <= now_dt:
            raise InvalidGrantError("grant binding has expired")
        expires_at_dt = min(expires_at_dt, issued_expires_at)
    expires_at = expires_at_dt.isoformat()
    decided_at = _now()
    claim = conn.execute(
        vault_requests.update()
        .where(
            vault_requests.c.id == request_id,
            vault_requests.c.request_type == "access",
            vault_requests.c.status == "pending",
        )
        .values(status="approved", decided_at=decided_at, callback_status="pending")
    )
    if claim.rowcount != 1:
        raise InvalidRequestError("grant approval request is not pending")
    grant_id = approval.grant_id
    grant_values = {
        "member_snapshot": json.dumps(members),
        "source_selector": json.dumps(selector),
        "session_id": session_id,
        "purpose": purpose,
        "status": "active",
        "request_id": request_id,
        "one_shot": 1 if one_shot_grant else 0,
        "created_at": now_dt.isoformat(),
        "expires_at": expires_at,
        "agent_ready": 1 if resident_cache_ready else 0,
        "agent_ready_at": now_dt.isoformat() if resident_cache_ready else None,
    }
    try:
        existing_grant = (
            conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id))
            .mappings()
            .first()
        )
        if existing_grant is not None:
            existing = dict(existing_grant)
            existing_selector = _loads(existing.get("source_selector")) or {}
            existing_one_shot = bool(int(existing.get("one_shot") or 0))
            if (
                existing.get("status") != "expired"
                or existing.get("request_id") != request_id
                or set(_grant_member_names(existing)) != set(members)
                or _source_selector_payload(existing_selector) != selector
                or existing.get("session_id") != session_id
                or existing.get("purpose") != purpose
                or existing_one_shot != one_shot_grant
            ):
                raise InvalidGrantError("grant id already exists")
            reused = conn.execute(
                vault_grants.update()
                .where(vault_grants.c.id == grant_id, vault_grants.c.status == "expired")
                .values(**grant_values)
            )
            if reused.rowcount != 1:
                raise InvalidGrantError("grant id already exists")
        else:
            conn.execute(vault_grants.insert().values(id=grant_id, **grant_values))
    except Exception:
        conn.execute(
            vault_requests.update()
            .where(vault_requests.c.id == request_id)
            .values(status="pending", decided_at=None, callback_status=None)
        )
        raise
    audit(
        conn,
        "granted",
        requester={"session_id": session_id} if session_id else None,
        delivery={
            "source_selector": selector,
            "purpose": purpose,
            "member_count": len(members),
            "grant_duration": duration["last_grant_ttl"],
        },
        request_id=request_id,
        grant_id=grant_id,
    )
    if remember_duration:
        save_vault_settings(conn, {"last_grant_ttl": duration["last_grant_ttl"]})
    row = conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().one()
    if not one_shot_grant:
        _approve_sibling_access_requests_for_grant(
            conn,
            request_id=request_id,
            members=members,
            session_id=session_id,
            purpose=purpose,
            decided_at=decided_at,
        )
    if resident_cache_ready:
        cache.put(grant_id, members, expires_at=expires_at)
    return _grant_payload(conn, dict(row), cache=cache)


def list_grants(
    conn: Connection,
    *,
    status: str | None = "active",
    session_id: str | None = None,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    user_context: Any = None,
) -> list[dict[str, Any]]:
    expire_grants(conn, cache=cache)
    query = select(vault_grants).order_by(vault_grants.c.created_at.desc(), vault_grants.c.id.desc())
    if status == "active":
        query = query.where(vault_grants.c.status.in_(ACTIVE_GRANT_STATES))
    elif status is not None:
        query = query.where(vault_grants.c.status == status)
    if session_id is not None:
        query = query.where(or_(vault_grants.c.session_id.is_(None), vault_grants.c.session_id == session_id))
    context = resolve_resource_access_context(user_context)
    rows = [dict(row) for row in conn.execute(query).mappings()]
    if not context.has_role("editor"):
        accessible_rows: list[dict[str, Any]] = []
        for row in rows:
            try:
                _require_grant_secret_access(conn, row, user_context=context)
            except VaultSecretAccessError:
                continue
            accessible_rows.append(row)
        rows = accessible_rows
    return [_grant_payload(conn, row, cache=cache) for row in rows]


def get_grant_created_by_request(
    conn: Connection,
    request_id: str,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
) -> dict[str, Any] | None:
    row = (
        conn.execute(
            select(vault_grants)
            .where(vault_grants.c.request_id == request_id)
            .order_by(vault_grants.c.created_at.desc(), vault_grants.c.id.desc())
            .limit(1)
        )
        .mappings()
        .first()
    )
    return _grant_payload(conn, dict(row), cache=cache) if row is not None else None


def expire_active_grants(
    conn: Connection,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    reason: str = "grant-expired-agent-cache-reset",
) -> int:
    rows = [
        dict(row)
        for row in conn.execute(select(vault_grants).where(vault_grants.c.status.in_(ACTIVE_GRANT_STATES))).mappings()
    ]
    return _expire_grant_rows(conn, rows, cache=cache, reason=reason)


def revoke_grant(
    conn: Connection,
    grant_id: str,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    user_context: Any = None,
) -> dict[str, Any]:
    row = conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().first()
    if row is None:
        raise GrantNotFoundError(grant_id)
    row_dict = dict(row)
    _require_grant_secret_access(conn, row_dict, user_context=user_context, management=True)
    if row_dict.get("status") not in ACTIVE_GRANT_STATES:
        raise GrantNotActiveError(grant_id)
    now = _now()
    conn.execute(
        vault_grants.update()
        .where(vault_grants.c.id == grant_id)
        .values(status="revoked", revoked_at=now, agent_ready=0, agent_ready_at=None)
    )
    cache.drop(grant_id)
    audit(conn, "grant-revoked", grant_id=grant_id, delivery={"grant_id": grant_id})
    updated = conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().one()
    return _grant_payload(conn, dict(updated), cache=cache)


def mark_grant_agent_ready(
    conn: Connection,
    grant_id: str,
    *,
    ttl_seconds: int | None = None,
    expires_at: str | None = None,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
) -> dict[str, Any]:
    row = conn.execute(
        select(vault_grants).where(
            vault_grants.c.id == grant_id,
            vault_grants.c.status == "active",
        )
    ).mappings().first()
    if row is None:
        raise GrantNotActiveError(grant_id)
    row_dict = dict(row)
    members = _grant_member_names(row_dict)
    if not members:
        raise InvalidGrantError("grant has no cached members")
    ready_at_dt = datetime.now(timezone.utc)
    ready_at = ready_at_dt.isoformat()
    values: dict[str, Any] = {"agent_ready": 1, "agent_ready_at": ready_at}
    if expires_at is not None:
        ready_expires_at = _parse_iso_datetime(expires_at)
        if ready_expires_at is None:
            raise InvalidGrantError("grant ready expiry is invalid")
        if ready_expires_at <= ready_at_dt:
            raise GrantNotActiveError(grant_id)
        values["expires_at"] = ready_expires_at.isoformat()
    elif ttl_seconds is not None:
        ttl = max(1, int(ttl_seconds))
        values["expires_at"] = (ready_at_dt + timedelta(seconds=ttl)).isoformat()
    result = conn.execute(
        vault_grants.update()
        .where(vault_grants.c.id == grant_id, vault_grants.c.status == "active")
        .values(**values)
    )
    if result.rowcount != 1:
        raise GrantNotActiveError(grant_id)
    row_dict = dict(conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().one())
    cache.put(grant_id, members, expires_at=row_dict.get("expires_at"))
    return _grant_payload(conn, row_dict, cache=cache)


def revoke_session_grants(
    conn: Connection,
    session_id: str,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
) -> int:
    rows = [
        dict(row)
        for row in conn.execute(
            select(vault_grants).where(vault_grants.c.status.in_(ACTIVE_GRANT_STATES), vault_grants.c.session_id == session_id)
        ).mappings()
    ]
    now = _now()
    revoked = 0
    for row in rows:
        result = conn.execute(
            vault_grants.update()
            .where(vault_grants.c.id == row["id"], vault_grants.c.status.in_(ACTIVE_GRANT_STATES))
            .values(status="revoked", revoked_at=now, agent_ready=0, agent_ready_at=None)
        )
        if result.rowcount != 1:
            continue
        cache.drop(row["id"])
        audit(
            conn,
            "grant-revoked-session-archived",
            grant_id=row["id"],
            delivery={"grant_id": row["id"], "session_id": session_id},
        )
        revoked += 1
    return revoked


def resource_policy_narrowed(previous: dict[str, Any] | None, updated: dict[str, Any] | None) -> bool:
    """Whether a Vault ACL update removes access granted by the prior policy."""

    from storage import resource_access_service

    return resource_access_service.resource_policy_narrowed(previous, updated)


def revoke_active_grants_for_secret_resource(
    conn: Connection,
    resource_id: str,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    reason: str = "grant-revoked-resource-access-narrowed",
) -> list[dict[str, Any]]:
    """Revoke active grants for the Vault secret identified by its ACL resource id."""

    row = conn.execute(select(vault_secrets).where(vault_secrets.c.id == resource_id).limit(1)).mappings().first()
    if row is None:
        return []
    secret_name = str(row["name"])
    active_rows = active_grant_rows_for_secret(conn, secret_name)
    if not active_rows:
        return []
    now = _now()
    revoked_rows: list[dict[str, Any]] = []
    for grant_row in active_rows:
        result = conn.execute(
            vault_grants.update()
            .where(vault_grants.c.id == grant_row["id"], vault_grants.c.status.in_(ACTIVE_GRANT_STATES))
            .values(status="revoked", revoked_at=now, agent_ready=0, agent_ready_at=None)
        )
        if result.rowcount != 1:
            continue
        cache.drop(str(grant_row["id"]))
        audit(
            conn,
            reason,
            secret_name=secret_name,
            grant_id=str(grant_row["id"]),
            delivery={"grant_id": str(grant_row["id"]), "resource_id": resource_id},
        )
        revoked_rows.append(grant_row)
    return revoked_rows


def find_active_grant_for_secret(
    conn: Connection,
    secret_name: str,
    *,
    session_id: str | None = None,
    purpose: str | None = None,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    reserve_one_shot: bool = False,
) -> dict[str, Any] | None:
    return find_active_grant_for_secrets(
        conn,
        [secret_name],
        session_id=session_id,
        purpose=purpose,
        cache=cache,
        reserve_one_shot=reserve_one_shot,
    )


def _grant_is_always_ask_for_members(
    conn: Connection,
    row: dict[str, Any],
) -> bool:
    try:
        return bool(int(row.get("one_shot") or 0))
    except (TypeError, ValueError):
        return False


def consume_one_shot_grant(
    conn: Connection,
    grant_id: str,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
) -> list[dict[str, str]]:
    row = conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().first()
    if row is None:
        raise GrantNotFoundError(grant_id)
    row_dict = dict(row)
    if row_dict.get("status") not in ACTIVE_GRANT_STATES:
        raise GrantNotActiveError(grant_id)
    if not _grant_is_always_ask_for_members(conn, row_dict):
        return []
    _expire_grant_rows(
        conn,
        [row_dict],
        cache=cache,
        reason="grant-expired-always-ask-consumed",
    )
    return agent_release_scopes_after_rows(conn, [row_dict], cache=cache)


def release_one_shot_reservation(
    conn: Connection,
    grant_id: str,
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
) -> dict[str, Any]:
    row = conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().first()
    if row is None:
        raise GrantNotFoundError(grant_id)
    row_dict = dict(row)
    if row_dict.get("status") != "reserved":
        raise GrantNotActiveError(grant_id)
    if not _grant_is_always_ask_for_members(conn, row_dict):
        raise InvalidGrantError("grant is not one-shot")
    result = conn.execute(
        vault_grants.update()
        .where(vault_grants.c.id == grant_id, vault_grants.c.status == "reserved")
        .values(status="active")
    )
    if result.rowcount != 1:
        raise GrantNotActiveError(grant_id)
    audit(conn, "grant-reservation-released", grant_id=grant_id, delivery={"grant_id": grant_id})
    row_dict = dict(conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().one())
    members = _grant_member_names(row_dict)
    if grant_row_has_resident_agent_ready(row_dict) and members:
        cache.put(grant_id, members, expires_at=row_dict.get("expires_at"))
    return _grant_payload(conn, row_dict, cache=cache)


def _reserve_one_shot_grant(
    conn: Connection,
    row: dict[str, Any],
    *,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
) -> dict[str, Any] | None:
    if not _grant_is_always_ask_for_members(conn, row):
        return _grant_payload(conn, row, cache=cache)
    if row.get("status") != "active":
        return None
    result = conn.execute(
        vault_grants.update()
        .where(vault_grants.c.id == row["id"], vault_grants.c.status == "active")
        .values(status="reserved")
    )
    if result.rowcount != 1:
        return None
    audit(conn, "grant-reserved-one-shot", grant_id=row["id"], delivery={"grant_id": row["id"]})
    updated = dict(conn.execute(select(vault_grants).where(vault_grants.c.id == row["id"])).mappings().one())
    return _grant_payload(conn, updated, cache=cache)


def find_active_grant_for_secrets(
    conn: Connection,
    secret_names: list[str],
    *,
    session_id: str | None = None,
    purpose: str | None = None,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    reserve_one_shot: bool = False,
) -> dict[str, Any] | None:
    expire_grants(conn, cache=cache)
    requested = {str(name) for name in secret_names if str(name)}
    if not requested:
        return None
    query = select(vault_grants).where(
        vault_grants.c.status.in_(ACTIVE_GRANT_STATES),
        or_(vault_grants.c.session_id.is_(None), vault_grants.c.session_id == session_id),
    )
    if purpose is not None:
        query = query.where(vault_grants.c.purpose == purpose)
    rows = [dict(row) for row in conn.execute(query).mappings()]
    candidates: list[tuple[bool, int, str, str, dict[str, Any]]] = []
    for row in rows:
        members = _loads(row.get("member_snapshot")) or []
        member_set = {str(name) for name in members if isinstance(name, str) and name}
        if not requested.issubset(member_set):
            continue
        payload = _grant_payload(conn, row, cache=cache)
        if payload.get("one_shot") is True and row.get("status") != "active":
            continue
        standard_only = all(_require_row(conn, name).get("protection") == "standard" for name in requested)
        candidates.append((
            standard_only or bool(payload.get("delivery_ready")),
            len(member_set),
            str(row.get("created_at") or ""),
            str(row.get("id") or ""),
            row,
        ))
    if not candidates:
        return None
    ready_candidates = [item for item in candidates if item[0]]
    if not ready_candidates:
        return None
    candidates = ready_candidates
    member_count = min(item[1] for item in candidates)
    _, _, _, _, row = max(
        (item for item in candidates if item[1] == member_count),
        key=lambda item: (item[2], item[3]),
    )
    payload = _grant_payload(conn, row, cache=cache)
    if reserve_one_shot and payload.get("one_shot") is True:
        return _reserve_one_shot_grant(conn, row, cache=cache)
    return payload


def resolve_secret_access(
    conn: Connection,
    name: str,
    *,
    session_id: str | None = None,
    purpose: str = "run",
    requester: Any = None,
    delivery: dict[str, Any] | None = None,
    create_request: bool = True,
    cache: VaultGrantRuntimeCache = GRANT_RUNTIME_CACHE,
    reserve_one_shot: bool = False,
    user_context: Any = None,
) -> dict[str, Any]:
    """Resolve an agent access attempt without exposing the value.

    Standard secrets can be delivered by existing one-shot avault paths. Protected
    secrets with an active metadata grant should be delivered by the resident
    avault agent; if the agent reports that its in-memory cache is gone, callers
    expire the grant and re-run this resolver to create a fresh approval request.
    """
    context = resolve_resource_access_context(user_context)
    row, record_entry = _resolve_record_ref(conn, name, user_context=context)
    secret_name = str(row["name"])
    record_name = str(record_entry["name"])
    if purpose not in GRANT_PURPOSES:
        raise InvalidRequestError(f"invalid grant purpose: {purpose!r}")
    _reject_keypair_value_delivery(row, secret_name)
    delivery_payload = dict(delivery or {})
    effective_session_id = (
        session_id
        or _payload_session_id(delivery_payload)
        or _payload_session_id(requester)
    )
    always_ask = _secret_always_ask(row)
    if row.get("protection") == "standard" and not always_ask:
        return {"status": "standard", "secret": _meta_payload(row), "envelope": record_entry["envelope"]}
    grant = find_active_grant_for_secret(
        conn,
        secret_name,
        session_id=effective_session_id,
        purpose=purpose,
        cache=cache,
        reserve_one_shot=reserve_one_shot,
    )
    if grant is not None:
        return {
            "status": "standard" if row.get("protection") == "standard" else "agent_delivery_ready",
            "secret": _meta_payload(row),
            "grant": grant,
            "envelope": record_entry["envelope"],
            "request": None,
        }
    request_payload = None
    if create_request:
        if effective_session_id is not None:
            delivery_payload["session_id"] = effective_session_id
        request_payload = create_access_request(
            conn,
            secret_name,
            source_selector={"env": [record_name]},
            purpose=purpose,
            requester=requester,
            delivery=delivery_payload,
            user_context=context,
        )
    return {"status": "approval_required", "secret": _meta_payload(row), "request": request_payload}


def _audit_access_snapshot(row: dict[str, Any]) -> tuple[bool, dict[str, Any] | None]:
    delivery = _loads(row.get("delivery"))
    if not isinstance(delivery, dict) or _AUDIT_ACCESS_SNAPSHOT_KEY not in delivery:
        return False, None
    snapshot = delivery.get(_AUDIT_ACCESS_SNAPSHOT_KEY)
    if not isinstance(snapshot, dict) or snapshot.get("version") != 1 or not isinstance(snapshot.get("resources"), list):
        return True, None
    return True, snapshot


def _audit_snapshot_allows(context: Any, snapshot: dict[str, Any]) -> bool:
    from storage import resource_access_service

    resources = snapshot.get("resources")
    if not isinstance(resources, list) or not resources:
        return False
    for resource in resources:
        if not isinstance(resource, dict) or not str(resource.get("name") or "") or not str(resource.get("resource_id") or ""):
            return False
        policy = resource.get("policy")
        if not resource_access_service.can_use_resource_policy_snapshot(context, policy):
            return False
    return True


def _audit_fast_path_allowed(context: Any) -> bool:
    """Allow local Owner administration and validated remote Editor access."""

    return context.is_instance_owner or (context.is_remote and context.has_role("editor"))


def _audit_reference_names_for_row(
    conn: Connection,
    row: dict[str, Any],
    *,
    request_members: dict[str, list[str] | None],
    grant_members: dict[str, list[str] | None],
) -> list[str]:
    names = {str(row.get("secret_name") or "")} - {""}
    request_id = str(row.get("request_id") or "")
    if request_id:
        if request_id not in request_members:
            request_row = conn.execute(select(vault_requests).where(vault_requests.c.id == request_id)).mappings().first()
            request_members[request_id] = _request_member_names(dict(request_row)) if request_row is not None else None
        members = request_members[request_id]
        if members is None:
            raise VaultSecretAccessError("Vault secret access is not permitted.")
        names.update(members)

    grant_id = str(row.get("grant_id") or "")
    if grant_id:
        if grant_id not in grant_members:
            grant_row = conn.execute(select(vault_grants).where(vault_grants.c.id == grant_id)).mappings().first()
            grant_members[grant_id] = _grant_member_names(dict(grant_row)) if grant_row is not None else None
        members = grant_members[grant_id]
        if members is None:
            raise VaultSecretAccessError("Vault secret access is not permitted.")
        names.update(members)
    return sorted(names)


def _deleted_audit_policy_snapshot(
    conn: Connection,
    name: str,
    *,
    tombstone_policies: dict[str, tuple[bool, Any]],
) -> tuple[bool, Any]:
    if name in tombstone_policies:
        return tombstone_policies[name]
    row = (
        conn.execute(
            select(vault_audit)
            .where(vault_audit.c.secret_name == name, vault_audit.c.event == "deleted")
            .order_by(vault_audit.c.ts.desc(), vault_audit.c.id.desc())
            .limit(1)
        )
        .mappings()
        .first()
    )
    if row is not None:
        present, snapshot = _audit_access_snapshot(dict(row))
        if present and snapshot is not None:
            for resource in snapshot["resources"]:
                if isinstance(resource, dict) and resource.get("name") == name:
                    result = (True, resource.get("policy"))
                    tombstone_policies[name] = result
                    return result
    result = (False, None)
    tombstone_policies[name] = result
    return result


def _audit_secret_name_allowed(
    conn: Connection,
    name: str,
    *,
    context: Any,
    access_by_name: dict[str, bool],
    tombstone_policies: dict[str, tuple[bool, Any]],
) -> bool:
    from storage import resource_access_service

    if name in access_by_name:
        return access_by_name[name]
    secret_row = conn.execute(select(vault_secrets.c.id).where(vault_secrets.c.name == name).limit(1)).first()
    if secret_row is not None:
        policy = resource_access_service.get_resource_policy(
            "vault_secret",
            str(secret_row.id),
            connection=conn,
        )
        allowed = bool(resource_access_service.can_use_resource_policy_snapshot(context, policy))
    else:
        has_tombstone, policy = _deleted_audit_policy_snapshot(
            conn,
            name,
            tombstone_policies=tombstone_policies,
        )
        allowed = bool(
            has_tombstone
            and resource_access_service.can_use_resource_policy_snapshot(context, policy)
        )
        if not has_tombstone:
            allowed = bool(_audit_fast_path_allowed(context))
    access_by_name[name] = allowed
    return allowed


def _require_audit_row_access(
    conn: Connection,
    row: dict[str, Any],
    *,
    user_context: Any = None,
    request_members: dict[str, list[str] | None] | None = None,
    grant_members: dict[str, list[str] | None] | None = None,
    access_by_name: dict[str, bool] | None = None,
    tombstone_policies: dict[str, tuple[bool, Any]] | None = None,
) -> None:
    context = resolve_resource_access_context(user_context)
    if _audit_fast_path_allowed(context):
        return

    snapshot_present, snapshot = _audit_access_snapshot(row)
    if snapshot_present:
        if snapshot is None or not _audit_snapshot_allows(context, snapshot):
            raise VaultSecretAccessError("Vault secret access is not permitted.")
        return

    names = _audit_reference_names_for_row(
        conn,
        row,
        request_members=request_members if request_members is not None else {},
        grant_members=grant_members if grant_members is not None else {},
    )
    if not names:
        if (
            context.has_role("editor")
        ):
            return
        raise VaultSecretAccessError("Vault secret access is not permitted.")
    name_access = access_by_name if access_by_name is not None else {}
    tombstones = tombstone_policies if tombstone_policies is not None else {}
    for name in names:
        if not _audit_secret_name_allowed(
            conn,
            name,
            context=context,
            access_by_name=name_access,
            tombstone_policies=tombstones,
        ):
            raise VaultSecretAccessError("Vault secret access is not permitted.")


def list_audit(
    conn: Connection,
    *,
    secret_name: str | None = None,
    limit: int = 100,
    user_context: Any = None,
) -> list[dict[str, Any]]:
    context = resolve_resource_access_context(user_context)
    requested_limit = max(0, limit)
    if requested_limit == 0:
        return []
    if _audit_fast_path_allowed(context):
        query = select(vault_audit).order_by(vault_audit.c.ts.desc(), vault_audit.c.id.desc())
        if secret_name is not None:
            query = query.where(vault_audit.c.secret_name == secret_name)
        rows = [dict(row) for row in conn.execute(query.limit(requested_limit)).mappings()]
        return [_audit_public_row(row) for row in rows]

    batch_size = max(
        _REMOTE_AUDIT_MIN_BATCH_SIZE,
        min(_REMOTE_AUDIT_MAX_BATCH_SIZE, requested_limit * 2),
    )
    accessible_rows: list[dict[str, Any]] = []
    cursor: tuple[str, str] | None = None
    request_members: dict[str, list[str] | None] = {}
    grant_members: dict[str, list[str] | None] = {}
    access_by_name: dict[str, bool] = {}
    tombstone_policies: dict[str, tuple[bool, Any]] = {}
    while len(accessible_rows) < requested_limit:
        query = select(vault_audit).order_by(vault_audit.c.ts.desc(), vault_audit.c.id.desc())
        if secret_name is not None:
            query = query.where(vault_audit.c.secret_name == secret_name)
        if cursor is not None:
            cursor_ts, cursor_id = cursor
            query = query.where(
                or_(
                    vault_audit.c.ts < cursor_ts,
                    and_(vault_audit.c.ts == cursor_ts, vault_audit.c.id < cursor_id),
                )
            )
        batch = [dict(row) for row in conn.execute(query.limit(batch_size)).mappings()]
        if not batch:
            break
        cursor = (str(batch[-1]["ts"]), str(batch[-1]["id"]))
        for row in batch:
            try:
                _require_audit_row_access(
                    conn,
                    row,
                    user_context=context,
                    request_members=request_members,
                    grant_members=grant_members,
                    access_by_name=access_by_name,
                    tombstone_policies=tombstone_policies,
                )
            except VaultSecretAccessError:
                continue
            accessible_rows.append(row)
            if len(accessible_rows) >= requested_limit:
                break
        if len(batch) < batch_size:
            break
    return [_audit_public_row(row) for row in accessible_rows]