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.

69.9 KB
Raw Blame
"""Local organization resource-policy state and evaluation helpers.

The control plane owns desired ACL intents. This module owns the local applied
policy used by future resource services, and deliberately stores no resource
content, prompts, paths, outputs, or secret values.
"""

from __future__ import annotations

import hashlib
import json
import time
from collections.abc import Mapping, Sequence
from contextlib import contextmanager
from dataclasses import dataclass, replace
from datetime import datetime, timezone
from typing import Any, Iterator

from sqlalchemy import select, update
from sqlalchemy import text as sqlalchemy_text
from sqlalchemy.engine import Connection

from storage.db import get_cached_sqlite_engine
from storage.agent_session_rows import reserve_write_lock
from storage.models import (
    agent_runs,
    message_deliveries,
    resource_access_groups,
    resource_access_policies,
    run_definitions,
    state_meta,
)
from vibe.authorization import (
    INSTANCE_ROLES,
    AuthorizationContext,
    context_from_session_payload,
    default_authorization_context,
    instance_owner_context,
)


RESOURCE_KINDS = frozenset({"agent", "vault_secret", "skill"})
ACCESS_LEVELS = frozenset({"public", "scope", "private"})
ORGANIZATION_ROLES = frozenset({"owner", "admin", "member"})
RESOURCE_USER_CONTEXT_METADATA_KEY = "resource_user_context"
LEGACY_DEFERRED_CONTEXT_MIGRATION_KEY = "migrations.legacy_deferred_resource_contexts.v1"
RESOURCE_ORGANIZATIONS_META_KEY = "resource_access_organizations"
HARNESS_ACCESS_FORBIDDEN_CODE = "harness_access_forbidden"
RESOURCE_BINDING_STATE_UNAVAILABLE = "unavailable"
RESOURCE_BINDING_STATE_UNPAIRED = "unpaired"
RESOURCE_BINDING_STATE_PARTIAL = "partial"
RESOURCE_BINDING_STATE_READY = "ready"
RESOURCE_BINDING_STATE_SEALED = "sealed"
RESOURCE_BINDING_STATUS_KEY = "binding_status"
_CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE = object()


@dataclass(frozen=True)
class ConfiguredResourceState:
    """One coherent read of the pairing identity used by deferred resources."""

    status: str
    instance_id: str | None
    instance_kind: str | None
    runtime_ready: bool


class ResourceAccessError(ValueError):
    """A stable, non-sensitive policy or intent validation error."""

    def __init__(self, code: str):
        super().__init__(code)
        self.code = code


# Compatibility name for callers that predate the shared authorization
# context. Resource services and transports now pass the same immutable object.
ResourceUserContext = AuthorizationContext


def _utc_now_iso() -> str:
    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")


def _clean_optional_string(value: Any, *, limit: int = 200) -> str | None:
    if not isinstance(value, str):
        return None
    cleaned = value.strip()
    if not cleaned or len(cleaned) > limit or any(ord(char) < 32 or ord(char) == 127 for char in cleaned):
        return None
    return cleaned


def _clean_positive_int(value: Any) -> int | None:
    if isinstance(value, bool):
        return None
    try:
        parsed = int(value)
    except (TypeError, ValueError):
        return None
    return parsed if parsed > 0 else None


def _required_identifier(value: Any, *, code: str) -> str:
    cleaned = _clean_optional_string(value)
    if cleaned is None:
        raise ResourceAccessError(code)
    return cleaned


def _validate_resource_kind(resource_kind: Any) -> str:
    if resource_kind not in RESOURCE_KINDS:
        raise ResourceAccessError("invalid_resource_kind")
    return str(resource_kind)


def _validate_access_level(access_level: Any) -> str:
    if access_level not in ACCESS_LEVELS:
        raise ResourceAccessError("invalid_resource_acl_intent")
    return str(access_level)


def _normalize_group_ids(value: Any) -> list[str]:
    if value is None:
        return []
    if not isinstance(value, (list, tuple, set, frozenset)):
        raise ResourceAccessError("invalid_resource_acl_intent")
    result: list[str] = []
    seen: set[str] = set()
    for item in value:
        group_id = _clean_optional_string(item)
        if group_id is None:
            raise ResourceAccessError("invalid_resource_acl_intent")
        if group_id not in seen:
            seen.add(group_id)
            result.append(group_id)
    return result


def _validate_policy_values(access_level: Any, group_ids: Any, organization_id: str | None) -> tuple[str, list[str]]:
    normalized_level = _validate_access_level(access_level)
    normalized_groups = _normalize_group_ids(group_ids)
    if normalized_level in {"public", "scope"} and not organization_id:
        # Public and scoped policies are organization semantics. A personal
        # resource stays private rather than accepting a policy no context can
        # safely authorize.
        raise ResourceAccessError("invalid_resource_acl_intent")
    if normalized_level == "scope":
        if not organization_id or not normalized_groups:
            raise ResourceAccessError("invalid_resource_acl_intent")
    elif normalized_groups:
        raise ResourceAccessError("invalid_resource_acl_intent")
    return normalized_level, normalized_groups


def normalize_policy_request(
    access_level: Any,
    group_ids: Any,
    organization_id: str | None,
) -> tuple[str, list[str]]:
    """Validate one policy request and normalize ignored non-scope groups."""

    if access_level in {"private", "public"}:
        group_ids = []
    return _validate_policy_values(access_level, group_ids, _clean_optional_string(organization_id))


def _context_from_mapping(
    payload: Mapping[str, Any] | None,
    *,
    is_remote: bool,
) -> ResourceUserContext:
    if not is_remote:
        return instance_owner_context()
    return context_from_session_payload(payload or {})


def current_resource_context(
    session_payload: Mapping[str, Any] | None = None,
    *,
    is_remote: bool | None = None,
) -> ResourceUserContext:
    """Return the request's local resource-access context.

    Callers that already parsed the signed session should pass it explicitly.
    The no-argument form is intentionally best-effort for future service-layer
    callers running inside the UI request context; outside a request it returns
    an untrusted anonymous context rather than guessing at an identity.
    """

    if isinstance(session_payload, AuthorizationContext):
        return session_payload
    if session_payload is not None or is_remote is not None:
        return _context_from_mapping(
            session_payload,
            is_remote=bool(is_remote if is_remote is not None else session_payload is not None),
        )

    try:
        from vibe.ui_compat import g, has_request_context

        if has_request_context():
            context = getattr(g, "authorization_context", None)
            return context if isinstance(context, AuthorizationContext) else AuthorizationContext(is_remote=True)
    except Exception:
        pass
    return AuthorizationContext()


def resolve_resource_access_context(
    user_context: ResourceUserContext | Mapping[str, Any] | None = None,
) -> ResourceUserContext:
    """Resolve ACL context, defaulting non-HTTP service calls to Instance Owner."""

    if isinstance(user_context, AuthorizationContext):
        return user_context
    if isinstance(user_context, Mapping):
        return current_resource_context(user_context, is_remote=True)

    context = current_resource_context()
    if context.is_remote:
        return context

    from vibe.ui_compat import has_request_context

    if has_request_context():
        return context
    # Outside a request, the invocation that is running owns the answer; with no
    # invocation either, this is a standalone local entry point and stays Owner.
    return default_authorization_context()


def ensure_harness_definition_write(
    user_context: ResourceUserContext | Mapping[str, Any] | None = None,
) -> ResourceUserContext:
    """Require Editor role for Harness definitions, independent of request origin."""

    context = resolve_resource_access_context(user_context)
    if not context.has_role("editor"):
        raise ResourceAccessError(HARNESS_ACCESS_FORBIDDEN_CODE)
    return context


def metadata_has_remote_resource_context(metadata: Mapping[str, Any] | None) -> bool:
    """Return whether persisted metadata records a remote-origin principal."""

    return isinstance(metadata, Mapping) and isinstance(
        metadata.get(RESOURCE_USER_CONTEXT_METADATA_KEY),
        Mapping,
    )


def metadata_allows_harness_runtime(
    metadata: Mapping[str, Any] | None,
) -> bool:
    """Return whether persisted user provenance has Editor runtime access."""

    if not metadata_has_remote_resource_context(metadata):
        return True
    try:
        context = resource_user_context_from_metadata(metadata)
    except ResourceAccessError:
        return False
    return bool(context is not None and context.has_role("editor"))


def _normalized_snapshot_email(email: str | None) -> str | None:
    return (email or "").strip().lower() or None


def metadata_with_resource_user_context(
    metadata: Mapping[str, Any] | None,
    user_context: ResourceUserContext | Mapping[str, Any] | None = None,
) -> dict[str, Any]:
    """Store the minimum remote identity needed to recheck deferred work."""

    result = dict(metadata or {})
    result.pop(RESOURCE_USER_CONTEXT_METADATA_KEY, None)
    context = resolve_resource_access_context(user_context)
    if not context.is_remote:
        return result

    result[RESOURCE_USER_CONTEXT_METADATA_KEY] = {
        "sub": context.subject,
        # Project ACLs bind ``email`` / ``email_domain`` principals, so a
        # snapshot without it denies deferred work the live request allowed.
        # Normalized the way ``_matching_binding_role`` compares it. Written
        # from the signed context after the key is dropped above, so caller
        # metadata cannot supply one.
        "email": _normalized_snapshot_email(context.email),
        "vibe_organization_id": context.organization_id,
        "vibe_organization_member_id": context.organization_member_id,
        "vibe_organization_role": context.organization_role,
        "vibe_group_ids": sorted(context.group_ids) if context.group_ids is not None else None,
        "vibe_membership_version": context.membership_version,
        "vibe_instance_id": context.instance_id,
        "vibe_instance_role": context.instance_role,
        "vibe_instance_access_source": context.instance_access_source,
        "vibe_instance_kind": context.instance_kind,
        "claims_issued_at": context.claims_issued_at,
        "vibe_instance_authorization_revision": context.authorization_revision,
        "authorization_expires_at": _resource_context_expires_at(context),
    }
    return result


def _resource_context_expires_at(context: ResourceUserContext) -> int:
    from vibe.remote_access import SESSION_AUTHORIZATION_REFRESH_SECONDS

    issued_at = context.claims_issued_at or int(time.time())
    return issued_at + SESSION_AUTHORIZATION_REFRESH_SECONDS


def resource_user_context_from_metadata(
    metadata: Mapping[str, Any] | None,
    *,
    now: int | None = None,
) -> ResourceUserContext | None:
    """Restore remote provenance for deferred authorization checks.

    The returned context retains the initiating role and ACL attributes.
    Deferred runtime executors still apply ``metadata_allows_harness_runtime``
    before doing work, so malformed or Viewer snapshots fail closed.

    The ``authorization_expires_at`` snapshot is recorded for audit but is no
    longer a hard execution cutoff: durable automation (Harness tasks/watches)
    must not be permanently suspended just because the creating browser session's
    refresh window elapsed. Active Organization membership is re-derived from the
    signed claims at execution time instead (avibe#1343 P1).
    """

    if not isinstance(metadata, Mapping):
        return None
    snapshot = metadata.get(RESOURCE_USER_CONTEXT_METADATA_KEY)
    if not isinstance(snapshot, Mapping):
        return None
    context = current_resource_context(snapshot, is_remote=True)

    # A persisted context is durable across re-pairing, so a Personal snapshot
    # must not authorize work after this installation moves to another
    # instance. Compare the server-owned binding whenever the current pairing
    # exposes one; legacy snapshots without an instance id remain unbound.
    configured = _configured_resource_instance()
    if context.instance_kind is not None and (
        configured is _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE or configured is None
    ):
        return None
    if configured is not _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE and configured is not None:
        paired_instance_id, paired_kind = configured
        from storage import remote_access_authorization_service

        ready = remote_access_authorization_service.binding_is_ready_for_pairing(
            instance_id=paired_instance_id,
            instance_kind=paired_kind,
            ensure=False,
            # Never bootstrap from this call: it can run while a SQLite writer
            # lock is already held (queued-delivery recheck). Opening a second
            # write connection here deadlocks; the interactive/UI path hoists
            # bootstrap via remote_access.binding_is_ready(..., bootstrap=True).
            bootstrap=False,
        )
        # An absent durable row is an upgrade artifact, not evidence the
        # pairing is wrong. Identity matching below still applies; the
        # authorization consumers (binding_is_ready) fail closed / bootstrap
        # on their own path. Only an explicit reconciling/mismatched row
        # means "do not project a Personal bypass from this snapshot".
        state = remote_access_authorization_service.load_instance_binding_state(
            ensure=False
        )
        if not ready:
            # Absent row (upgrade of a known-kind pairing) AND reconciling /
            # mismatched rows all fail closed for deferred/non-interactive
            # consumers. Interactive callers hoist bootstrap via
            # remote_access.binding_is_ready(..., bootstrap=True).
            return None
        if context.instance_kind is not None and (
            not paired_instance_id or not paired_kind
        ):
            return None
        snapshot_instance_id = context.instance_id
        if (
            snapshot_instance_id
            and paired_instance_id
            and snapshot_instance_id != paired_instance_id
        ):
            return None
        if context.instance_kind and paired_kind and context.instance_kind != paired_kind:
            return None
    from vibe.authorization import instance_kind_is_unsupported

    raw_snapshot_kind = snapshot.get("vibe_instance_kind")
    if instance_kind_is_unsupported(raw_snapshot_kind):
        # Same class as Web Push: a present-but-unrecognized kind is not a
        # no-kind legacy snapshot. Fail closed for deferred execution.
        return None
    if context.instance_kind is not None or raw_snapshot_kind is not None:
        return context
    if context.organization_id or context.instance_access_source == "organization_group":
        # Organization membership identity does not depend on the local pairing
        # being ready; an unpaired install must not retire Org deferred work.
        return context

    # Released snapshots predate the instance-kind field. Recover their kind
    # only when the snapshot still names the current server-owned instance. An
    # unbound legacy snapshot cannot be attributed to a re-paired Personal
    # instance, because doing so would turn old Organization work into a
    # Personal ACL bypass.
    pairing_state = _configured_resource_state()
    if pairing_state.status in {
        RESOURCE_BINDING_STATE_UNAVAILABLE,
        RESOURCE_BINDING_STATE_UNPAIRED,
    }:
        # Kindless snapshots cannot keep executing as a bare Editor when the
        # current pairing is unreadable or explicitly unpaired.
        return None
    paired_kind = pairing_state.instance_kind
    if paired_kind not in {"personal", "organization"}:
        # Preserve the valid legacy no-kind PAIRING path (runtime-ready
        # credentials, kind not yet backfilled — PARTIAL).
        return context
    if not context.instance_id:
        return None
    return replace(context, instance_kind=paired_kind)


def _as_context(user_context: ResourceUserContext | Mapping[str, Any] | None) -> ResourceUserContext:
    if isinstance(user_context, ResourceUserContext):
        return user_context
    if isinstance(user_context, Mapping):
        return _context_from_mapping(user_context, is_remote=True)
    return ResourceUserContext()


@contextmanager
def _connection(connection: Connection | None) -> Iterator[Connection]:
    if connection is not None:
        yield connection
        return
    engine = get_cached_sqlite_engine()
    with engine.begin() as active_connection:
        yield active_connection


def _configured_show_page_instance() -> tuple[str, str] | None | object:
    try:
        from config.v2_config import V2Config

        cloud = V2Config.load().remote_access.vibe_cloud
        credentials = cloud.runtime_credentials()
        if credentials is None:
            return None
        if not isinstance(credentials, (tuple, list)) or len(credentials) != 3:
            return _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE
        instance_id = _clean_optional_string(credentials[1])
        if instance_id is None or cloud.instance_kind not in {"personal", "organization"}:
            return _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE
    except (
        AttributeError,
        FileNotFoundError,
        IndexError,
        KeyError,
        OSError,
        TypeError,
        ValueError,
    ):
        return _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE
    return instance_id, cloud.instance_kind


def _configured_resource_state() -> ConfiguredResourceState:
    """Return one typed, fail-closed read of the configured pairing state.

    ``UNAVAILABLE`` is intentionally distinct from a successfully read
    unpaired configuration. Migration provenance must never be sealed because
    a transient config read failed.
    """

    try:
        from config.v2_config import V2Config

        loaded = V2Config.load(persist_migrations=False)
        # Only pairing/vibe_cloud recovery makes this reader UNAVAILABLE.
        # Unrelated-section warnings (e.g. Model Hub) must not block an
        # intact Vibe Cloud pairing or seal snapshots against it.
        pairing_warnings = tuple(
            warning
            for warning in getattr(loaded, "load_warnings", ())
            if (
                "remote_access" in warning
                or "vibe_cloud" in warning
                or (
                    "using recovery defaults" in warning
                    and "model_hub" not in warning
                    and "Recovered invalid config section" not in warning
                )
                or "not valid UTF-8" in warning
                or "JSON could not be parsed" in warning
                or "root is not an object" in warning
            )
        )
        if pairing_warnings:
            return ConfiguredResourceState(
                status=RESOURCE_BINDING_STATE_UNAVAILABLE,
                instance_id=None,
                instance_kind=None,
                runtime_ready=False,
            )
        cloud = loaded.remote_access.vibe_cloud
        raw_instance_id = cloud.instance_id
        instance_id = _clean_optional_string(raw_instance_id)
        if raw_instance_id not in (None, "") and instance_id is None:
            return ConfiguredResourceState(
                status=RESOURCE_BINDING_STATE_UNAVAILABLE,
                instance_id=None,
                instance_kind=None,
                runtime_ready=False,
            )
        instance_kind = (
            cloud.instance_kind if cloud.instance_kind in {"personal", "organization"} else None
        )
        credentials = cloud.runtime_credentials()
    except FileNotFoundError:
        # A missing config file is an authoritative unpaired install, not a
        # transient read failure. pair() must be allowed to redeem.
        return ConfiguredResourceState(
            status=RESOURCE_BINDING_STATE_UNPAIRED,
            instance_id=None,
            instance_kind=None,
            runtime_ready=False,
        )
    except Exception:
        return ConfiguredResourceState(
            status=RESOURCE_BINDING_STATE_UNAVAILABLE,
            instance_id=None,
            instance_kind=None,
            runtime_ready=False,
        )

    runtime_ready = False
    if credentials is not None:
        if not isinstance(credentials, (tuple, list)) or len(credentials) != 3:
            return ConfiguredResourceState(
                status=RESOURCE_BINDING_STATE_UNAVAILABLE,
                instance_id=instance_id,
                instance_kind=instance_kind,
                runtime_ready=False,
            )
        credential_instance_id = _clean_optional_string(credentials[1])
        runtime_ready = instance_id is not None and credential_instance_id == instance_id

    if instance_id is None:
        return ConfiguredResourceState(
            status=RESOURCE_BINDING_STATE_UNPAIRED,
            instance_id=None,
            instance_kind=instance_kind,
            runtime_ready=False,
        )
    if runtime_ready and instance_kind in {"personal", "organization"}:
        status = RESOURCE_BINDING_STATE_READY
    else:
        status = RESOURCE_BINDING_STATE_PARTIAL
    return ConfiguredResourceState(
        status=status,
        instance_id=instance_id,
        instance_kind=instance_kind,
        runtime_ready=runtime_ready,
    )


def _configured_resource_instance() -> tuple[str | None, str | None] | None | object:
    """Return the current complete pairing identity used to fence deferred resources."""

    configured = _configured_resource_state()
    if configured.status == RESOURCE_BINDING_STATE_UNAVAILABLE:
        return _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE
    if configured.status != RESOURCE_BINDING_STATE_READY:
        return None
    return configured.instance_id, configured.instance_kind


def _legacy_snapshot_has_organization_context(
    context: ResourceUserContext,
    snapshot: Mapping[str, Any],
) -> bool:
    """Detect Organization semantics retained by pre-binding snapshots."""

    return bool(
        context.organization_id
        or context.organization_member_id
        or context.organization_role
        or context.instance_access_source == "organization_group"
        or context.group_ids
        or any(
            snapshot.get(key)
            for key in (
                "vibe_organization_id",
                "vibe_organization_member_id",
                "vibe_organization_role",
                "vibe_group_ids",
            )
        )
    )


def _legacy_deferred_context_binding(
    snapshot: Mapping[str, Any],
    *,
    paired_instance_id: str,
    paired_kind: str,
) -> dict[str, str] | None:
    """Return a safe current binding for one pre-instance metadata snapshot."""

    context = current_resource_context(snapshot, is_remote=True)
    if context.instance_role not in INSTANCE_ROLES:
        return None

    raw_instance_id = snapshot.get("vibe_instance_id")
    snapshot_instance_id = _clean_optional_string(raw_instance_id)
    if raw_instance_id is not None and snapshot_instance_id is None:
        return None
    if snapshot_instance_id and snapshot_instance_id != paired_instance_id:
        return None

    raw_kind = snapshot.get("vibe_instance_kind")
    if raw_kind is not None and raw_kind not in {"personal", "organization"}:
        return None
    if raw_kind is not None and raw_kind != paired_kind:
        return None

    # The pairing kind is the only authoritative evidence for a legacy
    # snapshot that predates both binding fields. Explicit Organization claims
    # still contradict a Personal pairing, but access sources such as ``email``
    # are shared by Personal and Organization instances and cannot choose a
    # kind on their own.
    if paired_kind == "personal" and _legacy_snapshot_has_organization_context(context, snapshot):
        return None
    inferred_kind = raw_kind or paired_kind
    if inferred_kind != paired_kind:
        return None
    return {
        "vibe_instance_id": paired_instance_id,
        "vibe_instance_kind": paired_kind,
    }


def _connection_has_table(connection: Connection, table_name: str) -> bool:
    """True when the table exists on this connection's schema.

    The deferred-context migration also runs while an unversioned legacy
    schema is being stamped, where newer tables may not exist yet. A missing
    table simply has no deferred records to migrate.
    """

    return (
        connection.execute(
            sqlalchemy_text(
                "select 1 from sqlite_master where type = 'table' and name = :name"
            ),
            {"name": table_name},
        ).scalar_one_or_none()
        is not None
    )


def _metadata_snapshot_lacks_binding(metadata: Any) -> bool:
    """True when a deferred snapshot exists but carries no complete binding."""

    if not isinstance(metadata, dict):
        return False
    snapshot = metadata.get(RESOURCE_USER_CONTEXT_METADATA_KEY)
    if not isinstance(snapshot, Mapping):
        return False
    instance_id = _clean_optional_string(snapshot.get("vibe_instance_id"))
    kind = snapshot.get("vibe_instance_kind")
    return instance_id is None or kind not in {"personal", "organization"}


def _has_unbound_deferred_snapshots(connection: Connection) -> bool:
    """True when any released deferred record still lacks an instance binding.

    A fresh install has nothing to protect: sealing or pinning a marker there
    would only block the first real pairing. Only actual legacy snapshots make
    the first migration opportunity meaningful.
    """

    if _connection_has_table(connection, "run_definitions"):
        definition_rows = connection.execute(
            select(run_definitions.c.metadata_json).where(
                run_definitions.c.definition_type.in_(("scheduled", "watch"))
            )
        )
        for (metadata_json,) in definition_rows:
            try:
                metadata = json.loads(metadata_json or "{}")
            except (TypeError, ValueError):
                continue
            if _metadata_snapshot_lacks_binding(metadata):
                return True
    if _connection_has_table(connection, "agent_runs"):
        run_rows = connection.execute(
            select(agent_runs.c.metadata_json).where(
                agent_runs.c.status.in_(("pending", "queued", "processing", "running"))
            )
        )
        for (metadata_json,) in run_rows:
            try:
                metadata = json.loads(metadata_json or "{}")
            except (TypeError, ValueError):
                continue
            if _metadata_snapshot_lacks_binding(metadata):
                return True
    if _connection_has_table(connection, "message_deliveries"):
        from storage.delivery_states import DELIVERY_STATE_MATRIX

        executable_delivery_states = tuple(
            state
            for state, policy in DELIVERY_STATE_MATRIX.items()
            if policy.ordering != "terminal"
        )
        delivery_rows = connection.execute(
            select(message_deliveries.c.snapshot_json).where(
                message_deliveries.c.snapshot_json.is_not(None),
                message_deliveries.c.state.in_(executable_delivery_states),
            )
        )
        for (snapshot_json,) in delivery_rows:
            try:
                snapshot = json.loads(snapshot_json or "{}")
                metadata = json.loads(snapshot.get("metadata_json") or "{}")
            except (AttributeError, TypeError, ValueError):
                continue
            if _metadata_snapshot_lacks_binding(metadata):
                return True
    return False


def _deferred_provenance_time(value: Any) -> datetime | None:
    """Read a persisted timestamp only when it identifies an absolute instant."""

    if not isinstance(value, str):
        return None
    try:
        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
    except ValueError:
        return None
    return parsed if parsed.tzinfo is not None else None


def _migrate_deferred_metadata_value(
    metadata: Any,
    *,
    paired_instance_id: str,
    paired_kind: str,
    member_repair_cutoff: datetime | None = None,
    created_at: Any = None,
    updated_at: Any = None,
) -> dict[str, Any] | None:
    if not isinstance(metadata, dict):
        return None
    snapshot = metadata.get(RESOURCE_USER_CONTEXT_METADATA_KEY)
    if not isinstance(snapshot, Mapping):
        return None
    if member_repair_cutoff is not None:
        # Attribute an old Member authorization snapshot, not an immutable row.
        # Authorization re-snapshot and timestamped lifecycle writes advance
        # updated_at; diagnostics and stable-Agent rewrites can preserve it.
        # Current lifecycle checks still apply, including soft deletion.
        # Preserve their CURRENT metadata below. These clocks are not a complete
        # mutation history. Equal-second timestamps are ambiguous, so deny.
        if snapshot.get("vibe_instance_role") != "member" or any(
            (instant := _deferred_provenance_time(value)) is None or instant >= member_repair_cutoff
            for value in (created_at, updated_at)
        ):
            return None
    binding = _legacy_deferred_context_binding(
        snapshot,
        paired_instance_id=paired_instance_id,
        paired_kind=paired_kind,
    )
    if binding is None:
        return None
    if all(snapshot.get(key) == value for key, value in binding.items()):
        return None
    migrated = dict(metadata)
    migrated_snapshot = dict(snapshot)
    migrated_snapshot.update(binding)
    migrated[RESOURCE_USER_CONTEXT_METADATA_KEY] = migrated_snapshot
    return migrated


def migrate_legacy_deferred_resource_contexts(connection: Connection) -> dict[str, int]:
    """Bind released deferred metadata to the still-current runtime pairing.

    The migration is deliberately conservative and one-shot. It needs complete
    runtime credentials and a known server-owned instance kind, and it only
    updates a legacy snapshot when its existing instance evidence or explicit
    Organization claims agree with that pairing. A transient configuration read
    is not an unpaired state: it leaves the marker untouched so the same
    pairing can retry later. A successfully observed unpaired state is sealed,
    while a known instance with an unknown kind remains pending until that same
    instance is authoritatively classified.

    Repairing a completed pre-Member pass requires the original pairing/cutoff
    and an authorization snapshot whose row clocks precede it. Released
    diagnostic/reference writers preserve that snapshot without advancing the
    lifecycle clock; their current values survive the binding-only repair.
    No complete historical row immutability is inferred from those clocks.
    """

    # This migration decides from a marker, pairing config, durable binding and
    # several deferred row families before updating any of them. Reserve the
    # SQLite writer slot before the first read so that decision and seal share
    # one serialized state. This also covers callers that already hold a
    # transaction; reserve_write_lock is explicitly nested-transaction safe.
    reserve_write_lock(connection)

    def _counts(
        *,
        binding_status: str,
        definitions: int = 0,
        runs: int = 0,
        deliveries: int = 0,
    ) -> dict[str, int | str]:
        return {
            "legacy_deferred_definitions": definitions,
            "legacy_deferred_runs": runs,
            "legacy_deferred_deliveries": deliveries,
            RESOURCE_BINDING_STATUS_KEY: binding_status,
        }

    empty_unavailable = _counts(binding_status=RESOURCE_BINDING_STATE_UNAVAILABLE)
    marker_value = connection.execute(
        select(state_meta.c.value_json).where(
            state_meta.c.key == LEGACY_DEFERRED_CONTEXT_MIGRATION_KEY
        )
    ).scalar_one_or_none()
    marker: dict[str, Any] | None = None
    if marker_value is not None:
        try:
            parsed_marker = json.loads(marker_value)
        except (TypeError, ValueError):
            parsed_marker = None
        if not isinstance(parsed_marker, dict):
            # A corrupt marker cannot prove which pairing created the rows.
            # Preserve fail-closed behavior instead of trying to insert a
            # duplicate key or guessing a new binding.
            return _counts(binding_status=RESOURCE_BINDING_STATE_UNAVAILABLE)
        marker = parsed_marker
        marker_state = marker.get("state")
        if marker_state is not None and marker_state not in {"pending", "completed", "sealed_unattributed"}:
            return empty_unavailable
        if marker_state not in {"pending", "completed", "sealed_unattributed"}:
            marker_state = "completed" if marker.get("completed_at") else "pending"
        # Markers written by e64/d667 used ``completed`` with no instance ID
        # for an unpaired first opportunity. Preserve that terminal meaning;
        # never reinterpret it as a fresh migration opportunity.
        if marker_state == "completed" and marker.get("instance_id") is None:
            marker_state = "sealed_unattributed"
        marker = {**marker, "state": marker_state}

    configured = _configured_resource_state()
    if configured.status == RESOURCE_BINDING_STATE_UNAVAILABLE:
        # A read failure must not create ``pending(instance_id=None)`` or
        # rewrite a known marker. Startup/heartbeat will retry this operation.
        return empty_unavailable
    current_instance_id = configured.instance_id
    current_kind = (
        configured.instance_kind
        if configured.status == RESOURCE_BINDING_STATE_READY
        else None
    )
    # PARTIAL still carries a known instance ID; heartbeat/backfill uses it to
    # keep snapshots pending instead of sealing them as unattributed.

    def write_marker(
        *,
        state: str,
        instance_id: str | None,
        instance_kind: str | None = None,
    ) -> None:
        now = _utc_now_iso()
        payload: dict[str, Any] = {
            "schema_version": 3 if state == "completed" else 2,
            "state": state,
            "instance_id": instance_id,
            "updated_at": now,
        }
        if instance_kind in {"personal", "organization"}:
            payload["instance_kind"] = instance_kind
        if state == "completed":
            payload["completed_at"] = marker["completed_at"] if retry_member else now
        values = {
            "value_json": json.dumps(payload, sort_keys=True, separators=(",", ":")),
            "updated_at": now,
        }
        if marker is None:
            connection.execute(
                state_meta.insert().values(
                    key=LEGACY_DEFERRED_CONTEXT_MIGRATION_KEY,
                    **values,
                )
            )
        else:
            connection.execute(
                update(state_meta)
                .where(state_meta.c.key == LEGACY_DEFERRED_CONTEXT_MIGRATION_KEY)
                .values(**values)
            )

    # Released migrations omitted Member. Revisit only those snapshots when a
    # completed marker proves the SAME pairing identity and kind. Never reopen
    # an unattributed seal, infer missing provenance, or retry other roles.
    completed_at = _deferred_provenance_time(marker.get("completed_at")) if marker else None
    retry_member = bool(
        marker is not None
        and marker.get("state") == "completed"
        and type(marker.get("schema_version")) is int
        and marker.get("schema_version") in {1, 2}
        and completed_at is not None
        and configured.status == RESOURCE_BINDING_STATE_READY
        and current_instance_id is not None
        and marker.get("instance_id") == current_instance_id
        and current_kind in {"personal", "organization"}
        and marker.get("instance_kind") == current_kind
    )
    if marker is not None and marker.get("state") in {"completed", "sealed_unattributed"} and not retry_member:
        return _counts(binding_status=RESOURCE_BINDING_STATE_SEALED)

    raw_marker_instance_id = marker.get("instance_id") if marker else None
    marker_instance_id = (
        _clean_optional_string(raw_marker_instance_id) if marker else None
    )
    if marker and raw_marker_instance_id is not None and marker_instance_id is None:
        # A malformed marker cannot prove ownership. Keep the existing value
        # intact and fail closed rather than guessing a new pairing.
        return _counts(binding_status=RESOURCE_BINDING_STATE_UNAVAILABLE)
    if marker is not None:
        if marker_instance_id is None:
            # No first pairing was available to prove ownership. A later
            # pairing must not be allowed to claim these records.
            write_marker(state="sealed_unattributed", instance_id=None)
            return _counts(binding_status=RESOURCE_BINDING_STATE_SEALED)
        if current_instance_id is None:
            if configured.status == RESOURCE_BINDING_STATE_UNPAIRED:
                write_marker(state="sealed_unattributed", instance_id=marker_instance_id)
                return _counts(binding_status=RESOURCE_BINDING_STATE_SEALED)
            return _counts(binding_status=configured.status)
        if current_instance_id != marker_instance_id:
            write_marker(state="sealed_unattributed", instance_id=marker_instance_id)
            return _counts(binding_status=RESOURCE_BINDING_STATE_SEALED)

    if configured.status == RESOURCE_BINDING_STATE_UNPAIRED:
        if marker is None and not _has_unbound_deferred_snapshots(connection):
            # A fresh install has no legacy snapshots to protect. Writing a
            # sealed marker here would only block the first real pairing.
            return _counts(binding_status=RESOURCE_BINDING_STATE_UNPAIRED)
        write_marker(state="sealed_unattributed", instance_id=current_instance_id)
        return _counts(binding_status=RESOURCE_BINDING_STATE_SEALED)
    if configured.status != RESOURCE_BINDING_STATE_READY:
        # A PARTIAL pairing still records its identity: the pending marker is
        # what lets the SAME instance complete after credential repair while a
        # DIFFERENT instance stays sealed out.
        write_marker(state="pending", instance_id=current_instance_id)
        return _counts(binding_status=configured.status)
    if current_instance_id is None or current_kind not in {"personal", "organization"}:
        # Defensive guard for a future state-reader change. This branch is
        # never authoritative enough to complete a migration.
        return _counts(binding_status=RESOURCE_BINDING_STATE_PARTIAL)
    # C2 fence: this migration can run from a bare ensure_sqlite_state()
    # without config_file_lock (taking it here would invert the canonical
    # lock order against a peer holding config lock -> migration lock).
    # Instead, refuse to bind snapshots when the durable binding row exists
    # and disagrees with the pairing snapshot just read: a peer is mid-
    # reclassification and owns this migration through its own transition.
    from storage.remote_access_authorization_service import (
        INSTANCE_BINDING_STATE_RECONCILING as _BINDING_RECONCILING,
        _load_binding_state_from_connection as _load_binding_row,
    )

    try:
        binding_row = _load_binding_row(connection)
    except Exception:
        binding_row = None
    if binding_row is not None:
        row_id = binding_row.get("instance_id")
        row_kind = binding_row.get("instance_kind")
        row_state = binding_row.get("state")
        if retry_member and row_state != RESOURCE_BINDING_STATE_READY:
            return _counts(binding_status=RESOURCE_BINDING_STATE_PARTIAL)
        identity_matches = row_id == current_instance_id and (
            row_kind == current_kind
            or (row_state == _BINDING_RECONCILING and row_kind in {None, current_kind})
        )
        if not identity_matches:
            if not retry_member:
                write_marker(state="pending", instance_id=current_instance_id)
            return _counts(binding_status=RESOURCE_BINDING_STATE_PARTIAL)
    else:
        # Known-kind config with no durable binding row is an upgrade
        # artifact, not a validated pairing. Leave the opportunity pending
        # so a later heartbeat/bootstrap can attribute snapshots after the
        # server-owned kind is confirmed.
        if not retry_member:
            write_marker(state="pending", instance_id=current_instance_id)
        return _counts(binding_status=RESOURCE_BINDING_STATE_PARTIAL)
    paired_instance_id = current_instance_id
    paired_kind = current_kind

    counts = {
        "legacy_deferred_definitions": 0,
        "legacy_deferred_runs": 0,
        "legacy_deferred_deliveries": 0,
        RESOURCE_BINDING_STATUS_KEY: RESOURCE_BINDING_STATE_READY,
    }
    definition_rows = (
        connection.execute(
            select(run_definitions.c.id, run_definitions.c.metadata_json,
                   run_definitions.c.created_at, run_definitions.c.updated_at).where(
                run_definitions.c.definition_type.in_(("scheduled", "watch"))
            )
        ).mappings()
        if _connection_has_table(connection, "run_definitions")
        else ()
    )
    for row in definition_rows:
        try:
            metadata = json.loads(row["metadata_json"] or "{}")
        except (TypeError, ValueError):
            continue
        migrated = _migrate_deferred_metadata_value(
            metadata,
            paired_instance_id=paired_instance_id,
            paired_kind=paired_kind,
            member_repair_cutoff=completed_at if retry_member else None,
            created_at=row["created_at"],
            updated_at=row["updated_at"],
        )
        if migrated is None:
            continue
        connection.execute(
            update(run_definitions)
            .where(run_definitions.c.id == row["id"])
            .values(
                metadata_json=json.dumps(
                    migrated,
                    ensure_ascii=False,
                    sort_keys=True,
                    separators=(",", ":"),
                )
            )
        )
        counts["legacy_deferred_definitions"] += 1

    run_rows = (
        connection.execute(
            select(agent_runs.c.id, agent_runs.c.metadata_json,
                   agent_runs.c.created_at, agent_runs.c.updated_at)
            .where(agent_runs.c.status.in_(("pending", "queued", "processing", "running")))
        ).mappings()
        if _connection_has_table(connection, "agent_runs")
        else ()
    )
    for row in run_rows:
        try:
            metadata = json.loads(row["metadata_json"] or "{}")
        except (TypeError, ValueError):
            continue
        migrated = _migrate_deferred_metadata_value(
            metadata,
            paired_instance_id=paired_instance_id,
            paired_kind=paired_kind,
            member_repair_cutoff=completed_at if retry_member else None,
            created_at=row["created_at"],
            updated_at=row["updated_at"],
        )
        if migrated is None:
            continue
        connection.execute(
            update(agent_runs)
            .where(agent_runs.c.id == row["id"])
            .values(
                metadata_json=json.dumps(
                    migrated,
                    ensure_ascii=False,
                    sort_keys=True,
                    separators=(",", ":"),
                ),
                updated_at=_utc_now_iso(),
            )
        )
        counts["legacy_deferred_runs"] += 1

    from storage.delivery_states import DELIVERY_STATE_MATRIX

    executable_delivery_states = tuple(
        state
        for state, policy in DELIVERY_STATE_MATRIX.items()
        if policy.ordering != "terminal"
    )
    delivery_rows = (
        connection.execute(
            select(
                message_deliveries.c.id,
                message_deliveries.c.snapshot_json,
                message_deliveries.c.submitted_at.label("created_at"),
                message_deliveries.c.updated_at,
            ).where(
                message_deliveries.c.snapshot_json.is_not(None),
                message_deliveries.c.state.in_(executable_delivery_states),
            )
        ).mappings()
        if _connection_has_table(connection, "message_deliveries")
        else ()
    )
    for row in delivery_rows:
        try:
            snapshot = json.loads(row["snapshot_json"] or "{}")
            metadata = json.loads(snapshot.get("metadata_json") or "{}")
        except (AttributeError, TypeError, ValueError):
            continue
        migrated_metadata = _migrate_deferred_metadata_value(
            metadata,
            paired_instance_id=paired_instance_id,
            paired_kind=paired_kind,
            member_repair_cutoff=completed_at if retry_member else None,
            created_at=row["created_at"],
            updated_at=row["updated_at"],
        )
        if migrated_metadata is None:
            continue
        snapshot["metadata_json"] = json.dumps(
            migrated_metadata,
            ensure_ascii=False,
            sort_keys=True,
            separators=(",", ":"),
        )
        snapshot_json = json.dumps(
            snapshot,
            ensure_ascii=False,
            sort_keys=True,
            separators=(",", ":"),
        )
        snapshot_sha256 = hashlib.sha256(snapshot_json.encode("utf-8")).hexdigest()
        connection.execute(
            update(message_deliveries)
            .where(message_deliveries.c.id == row["id"])
            .values(
                snapshot_json=snapshot_json,
                snapshot_sha256=snapshot_sha256,
                updated_at=_utc_now_iso(),
            )
        )
        counts["legacy_deferred_deliveries"] += 1
    write_marker(
        state="completed",
        instance_id=paired_instance_id,
        instance_kind=paired_kind,
    )
    return counts

def _stored_resource_organizations(connection: Connection) -> set[str]:
    raw_value = connection.execute(
        select(state_meta.c.value_json).where(state_meta.c.key == RESOURCE_ORGANIZATIONS_META_KEY)
    ).scalar_one_or_none()
    try:
        values = json.loads(raw_value) if raw_value else []
    except (TypeError, ValueError):
        return set()
    if not isinstance(values, list):
        return set()
    return {
        organization
        for value in values
        if (organization := _clean_optional_string(value)) is not None
    }


def _store_resource_organizations(connection: Connection, organizations: set[str]) -> None:
    connection.execute(state_meta.delete().where(state_meta.c.key == RESOURCE_ORGANIZATIONS_META_KEY))
    if not organizations:
        return
    connection.execute(
        state_meta.insert().values(
            key=RESOURCE_ORGANIZATIONS_META_KEY,
            value_json=json.dumps(sorted(organizations), separators=(",", ":")),
            updated_at=_utc_now_iso(),
        )
    )


def remember_resource_organization(connection: Connection, organization_id: str | None) -> None:
    organization = _clean_optional_string(organization_id)
    if organization is None:
        return
    organizations = _stored_resource_organizations(connection)
    if organization in organizations:
        return
    organizations.add(organization)
    _store_resource_organizations(connection, organizations)


def forget_resource_organization(connection: Connection, organization_id: str) -> None:
    organization = _required_identifier(organization_id, code="invalid_organization_id")
    organizations = _stored_resource_organizations(connection)
    if organization not in organizations:
        return
    organizations.remove(organization)
    _store_resource_organizations(connection, organizations)


def list_resource_organization_ids(*, connection: Connection | None = None) -> list[str]:
    """List current and pending-empty-index organizations for device sync."""

    with _connection(connection) as conn:
        organizations = _stored_resource_organizations(conn)
        organizations.update(
            str(row.organization_id)
            for row in conn.execute(
                select(resource_access_policies.c.organization_id)
                .where(resource_access_policies.c.resource_kind.in_(RESOURCE_KINDS))
                .where(resource_access_policies.c.organization_id.is_not(None))
                .distinct()
            )
            if row.organization_id
        )
    return sorted(organizations)


def _policy_row(connection: Connection, resource_kind: str, resource_id: str) -> dict[str, Any] | None:
    row = connection.execute(
        select(resource_access_policies)
        .where(resource_access_policies.c.resource_kind == resource_kind)
        .where(resource_access_policies.c.resource_id == resource_id)
        .limit(1)
    ).mappings().first()
    return dict(row) if row else None


def _policy_groups(connection: Connection, resource_kind: str, resource_id: str) -> list[str]:
    return [
        str(row["group_id"])
        for row in connection.execute(
            select(resource_access_groups.c.group_id)
            .where(resource_access_groups.c.resource_kind == resource_kind)
            .where(resource_access_groups.c.resource_id == resource_id)
            .order_by(resource_access_groups.c.group_id)
        ).mappings()
    ]


def _serialize_policy(connection: Connection, policy: Mapping[str, Any]) -> dict[str, Any]:
    data = dict(policy)
    data["group_ids"] = _policy_groups(connection, str(data["resource_kind"]), str(data["resource_id"]))
    return data


def get_resource_policy(
    resource_kind: str,
    resource_id: str,
    *,
    connection: Connection | None = None,
) -> dict[str, Any] | None:
    kind = _validate_resource_kind(resource_kind)
    identifier = _required_identifier(resource_id, code="invalid_resource_id")
    with _connection(connection) as conn:
        policy = _policy_row(conn, kind, identifier)
        return _serialize_policy(conn, policy) if policy else None


def list_resource_policies(
    *,
    resource_kind: str | None = None,
    organization_id: str | None = None,
    owner_user_id: str | None = None,
    connection: Connection | None = None,
) -> list[dict[str, Any]]:
    kind = _validate_resource_kind(resource_kind) if resource_kind is not None else None
    organization = _clean_optional_string(organization_id) if organization_id is not None else None
    owner = _clean_optional_string(owner_user_id) if owner_user_id is not None else None
    statement = select(resource_access_policies).order_by(
        resource_access_policies.c.resource_kind,
        resource_access_policies.c.resource_id,
    )
    if kind is not None:
        statement = statement.where(resource_access_policies.c.resource_kind == kind)
    else:
        # Unscoped listings exclude retired resource kinds so preserved legacy
        # rows (e.g. show_page policies written by older releases) degrade
        # silently instead of surfacing through sync or onboarding queries.
        statement = statement.where(resource_access_policies.c.resource_kind.in_(RESOURCE_KINDS))
    if organization is not None:
        statement = statement.where(resource_access_policies.c.organization_id == organization)
    if owner is not None:
        statement = statement.where(resource_access_policies.c.owner_user_id == owner)
    with _connection(connection) as conn:
        return [_serialize_policy(conn, row) for row in conn.execute(statement).mappings()]


def ensure_resource_policy(
    connection: Connection,
    *,
    resource_kind: str,
    resource_id: str,
    organization_id: str | None,
    owner_user_id: str | None,
    owner_email: str | None = None,
    access_level: str = "private",
    group_ids: Sequence[str] | None = None,
    created_by_user_id: str | None = None,
    updated_by_user_id: str | None = None,
    policy_revision: int = 0,
    last_applied_control_plane_revision: int | None = None,
) -> dict[str, Any]:
    """Create a resource policy if it does not already exist.

    Resource-specific services should use this at creation time. It never
    overwrites an existing policy, which prevents a late resource registration
    from replacing a control-plane intent already applied locally.
    """

    kind = _validate_resource_kind(resource_kind)
    identifier = _required_identifier(resource_id, code="invalid_resource_id")
    organization = _clean_optional_string(organization_id)
    owner = _clean_optional_string(owner_user_id)
    normalized_level, normalized_groups = _validate_policy_values(access_level, group_ids, organization)
    if policy_revision < 0 or last_applied_control_plane_revision is not None and last_applied_control_plane_revision < 0:
        raise ResourceAccessError("invalid_resource_acl_intent")
    existing = _policy_row(connection, kind, identifier)
    if existing:
        remember_resource_organization(connection, existing.get("organization_id"))
        return _serialize_policy(connection, existing)
    remember_resource_organization(connection, organization)
    now = _utc_now_iso()
    connection.execute(
        resource_access_policies.insert().values(
            resource_kind=kind,
            resource_id=identifier,
            organization_id=organization,
            owner_user_id=owner,
            owner_email=_clean_optional_string(owner_email, limit=320),
            access_level=normalized_level,
            created_by_user_id=_clean_optional_string(created_by_user_id),
            updated_by_user_id=_clean_optional_string(updated_by_user_id),
            policy_revision=policy_revision,
            last_applied_control_plane_revision=last_applied_control_plane_revision,
            created_at=now,
            updated_at=now,
        )
    )
    _replace_policy_groups(connection, kind, identifier, organization, normalized_groups, now)
    policy = _policy_row(connection, kind, identifier)
    assert policy is not None
    return _serialize_policy(connection, policy)


def delete_resource_policy(connection: Connection, resource_kind: str, resource_id: str) -> bool:
    """Delete local policy state when its local resource is permanently removed."""

    kind = _validate_resource_kind(resource_kind)
    identifier = _required_identifier(resource_id, code="invalid_resource_id")
    policy = _policy_row(connection, kind, identifier)
    if policy is not None:
        remember_resource_organization(connection, policy.get("organization_id"))
    connection.execute(
        resource_access_groups.delete()
        .where(resource_access_groups.c.resource_kind == kind)
        .where(resource_access_groups.c.resource_id == identifier)
    )
    result = connection.execute(
        resource_access_policies.delete()
        .where(resource_access_policies.c.resource_kind == kind)
        .where(resource_access_policies.c.resource_id == identifier)
    )
    return bool(result.rowcount)


def _replace_policy_groups(
    connection: Connection,
    resource_kind: str,
    resource_id: str,
    organization_id: str | None,
    group_ids: Sequence[str],
    now: str,
) -> None:
    connection.execute(
        resource_access_groups.delete()
        .where(resource_access_groups.c.resource_kind == resource_kind)
        .where(resource_access_groups.c.resource_id == resource_id)
    )
    if not group_ids:
        return
    if organization_id is None:
        raise ResourceAccessError("invalid_resource_acl_intent")
    connection.execute(
        resource_access_groups.insert(),
        [
            {
                "resource_kind": resource_kind,
                "resource_id": resource_id,
                "group_id": group_id,
                "organization_id": organization_id,
                "created_at": now,
            }
            for group_id in group_ids
        ],
    )


def _policy_allows(
    context: ResourceUserContext,
    resource_kind: str,
    resource_id: str,
    policy: Mapping[str, Any] | None,
    group_ids: Sequence[str],
) -> bool:
    # Current-instance operators use every supported resource without rewriting
    # its stored ownership or ACL. Protected Vault proofs are enforced by use.
    if context.can_manage_instance:
        return True
    if resource_kind == "agent" and context.is_personal_instance:
        return context.can_use_resource(resource_kind)
    # Skill and Vault ACL rows remain persisted for compatibility, but Editor
    # runtime access intentionally ignores them for validated remote sessions.
    # Direct non-remote contexts still use the stored policy so service-level
    # ACL checks cannot be bypassed by a caller-supplied role alone.
    #
    # A Personal Instance is the other half of that same rule: it has no
    # Organization to be an active member of, so it qualifies on the SIGNED
    # instance kind (as ``agent`` above already does) rather than on missing
    # Organization claims. Management is unaffected — metadata writes still go
    # through ``_require_secret_resource_management`` and protected secrets still
    # require their approval and proof.
    if resource_kind in {"skill", "vault_secret"}:
        if (
            context.is_remote
            and context.has_role("editor")
            and (context.is_active_organization_member or context.is_personal_instance)
        ):
            return True
    if not context.can_use_resource(resource_kind):
        return False
    if policy is None:
        return False

    owner_user_id = _clean_optional_string(policy.get("owner_user_id"))
    if policy.get("access_level") == "private":
        if not (owner_user_id and context.subject and owner_user_id == context.subject):
            return False
        organization_id = _clean_optional_string(policy.get("organization_id"))
        return bool(
            not organization_id
            or context.is_active_organization_member and context.organization_id == organization_id
        )

    organization_id = _clean_optional_string(policy.get("organization_id"))
    if not organization_id or context.organization_id != organization_id or not context.is_active_organization_member:
        return False
    if policy.get("access_level") == "public":
        return True
    if policy.get("access_level") == "scope":
        # Missing and empty are intentionally distinct: a missing group claim
        # must fail closed, and an active member with no matching group also
        # cannot use a scoped resource.
        return bool(context.group_ids and set(group_ids).intersection(context.group_ids))
    return False


def _policy_allows_management(context: ResourceUserContext, policy: Mapping[str, Any] | None) -> bool:
    if context.is_instance_owner:
        return True
    if context.has_role("member"):
        return True
    if policy is None:
        return False
    # Skills and Vault ACL rows are retained for compatibility, but MVP runtime
    # access and management follow the Instance Editor capability directly.
    if policy.get("resource_kind") in {"skill", "vault_secret"}:
        return context.has_role("editor")
    return bool(
        context.has_role("editor")
        and context.subject
        and context.subject == _clean_optional_string(policy.get("owner_user_id"))
    )


def _policy_allows_owner_control(
    context: ResourceUserContext,
    policy: Mapping[str, Any] | None,
) -> bool:
    """Allow high-impact sharing actions only to the resource owner."""

    if context.is_instance_owner:
        return True
    if policy is None:
        return context.is_instance_owner
    if not context.can_use_resource(str(policy.get("resource_kind") or "")):
        return False
    owner_user_id = _clean_optional_string(policy.get("owner_user_id"))
    if not (owner_user_id and context.subject and owner_user_id == context.subject):
        return False
    organization_id = _clean_optional_string(policy.get("organization_id"))
    return bool(
        not organization_id
        or context.is_active_organization_member
        and context.organization_id == organization_id
    )


def can_use_resource_policy_snapshot(
    user_context: ResourceUserContext | Mapping[str, Any] | None,
    policy: Mapping[str, Any] | None,
) -> bool:
    """Evaluate a server-owned policy snapshot for immutable history."""

    context = _as_context(user_context)
    if policy is not None and not isinstance(policy, Mapping):
        return False
    resource_kind = policy.get("resource_kind") if policy is not None else None
    if resource_kind not in RESOURCE_KINDS:
        return False
    group_ids = policy.get("group_ids") if policy is not None else []
    if not isinstance(group_ids, (list, tuple, set, frozenset)):
        return False
    return _policy_allows(
        context,
        str(resource_kind),
        str(policy.get("resource_id") or ""),
        policy,
        [str(group_id) for group_id in group_ids],
    )


def can_manage_resource_policy_snapshot(
    user_context: ResourceUserContext | Mapping[str, Any] | None,
    policy: Mapping[str, Any] | None,
) -> bool:
    """Evaluate management access from a server-owned policy snapshot."""

    if policy is not None and not isinstance(policy, Mapping):
        return False
    return _policy_allows_management(_as_context(user_context), policy)


def can_use_resource(
    user_context: ResourceUserContext | Mapping[str, Any] | None,
    resource_kind: str,
    resource_id: str,
    *,
    connection: Connection | None = None,
) -> bool:
    context = _as_context(user_context)
    kind = _validate_resource_kind(resource_kind)
    identifier = _required_identifier(resource_id, code="invalid_resource_id")
    with _connection(connection) as conn:
        policy = _policy_row(conn, kind, identifier)
        groups = _policy_groups(conn, kind, identifier) if policy else []
        return _policy_allows(
            context,
            kind,
            identifier,
            policy,
            groups,
        )


def can_manage_resource_acl(
    user_context: ResourceUserContext | Mapping[str, Any] | None,
    resource_kind: str,
    resource_id: str,
    *,
    connection: Connection | None = None,
) -> bool:
    context = _as_context(user_context)
    kind = _validate_resource_kind(resource_kind)
    identifier = _required_identifier(resource_id, code="invalid_resource_id")
    with _connection(connection) as conn:
        policy = _policy_row(conn, kind, identifier)
    return _policy_allows_management(context, policy)


def can_control_resource_sharing(
    user_context: ResourceUserContext | Mapping[str, Any] | None,
    resource_kind: str,
    resource_id: str,
    *,
    connection: Connection | None = None,
) -> bool:
    """Return whether the resource owner may widen anonymous sharing."""

    context = _as_context(user_context)
    kind = _validate_resource_kind(resource_kind)
    identifier = _required_identifier(resource_id, code="invalid_resource_id")
    with _connection(connection) as conn:
        policy = _policy_row(conn, kind, identifier)
    return _policy_allows_owner_control(context, policy)


def _row_resource_id(row: Any) -> str | None:
    keys = ("resource_id", "id", "session_id", "name", "key")
    if isinstance(row, Mapping):
        for key in keys:
            value = _clean_optional_string(row.get(key))
            if value is not None:
                return value
        return None
    for key in keys:
        value = _clean_optional_string(getattr(row, key, None))
        if value is not None:
            return value
    return None


def filter_accessible_resources(
    user_context: ResourceUserContext | Mapping[str, Any] | None,
    resource_kind: str,
    rows: Sequence[Any],
    *,
    connection: Connection | None = None,
) -> list[Any]:
    """Filter generic resource rows without coupling to any resource domain.

    Rows may be mappings or objects and should expose one of `resource_id`,
    `id`, `session_id`, `name`, or `key`. Unknown rows are excluded rather than
    accidentally exposed.
    """

    context = _as_context(user_context)
    kind = _validate_resource_kind(resource_kind)
    candidates = [(row, _row_resource_id(row)) for row in rows]
    identifiers = [identifier for _, identifier in candidates if identifier is not None]
    if not identifiers:
        return []
    with _connection(connection) as conn:
        policy_rows = conn.execute(
            select(resource_access_policies)
            .where(resource_access_policies.c.resource_kind == kind)
            .where(resource_access_policies.c.resource_id.in_(identifiers))
        ).mappings()
        policies = {str(row["resource_id"]): dict(row) for row in policy_rows}
        groups = {
            identifier: _policy_groups(conn, kind, identifier)
            for identifier in policies
        }
    return [
        row
        for row, identifier in candidates
        if identifier is not None
        and _policy_allows(
            context,
            kind,
            identifier,
            policies.get(identifier),
            groups.get(identifier, []),
        )
    ]


def resource_policy_narrowed(
    previous: Mapping[str, Any] | None,
    updated: Mapping[str, Any] | None,
) -> bool:
    """Return whether an applied policy removes any previously granted use."""

    if not previous or not updated:
        return False
    previous_level = str(previous.get("access_level") or "")
    updated_level = str(updated.get("access_level") or "")
    if previous_level == "public":
        return updated_level in {"scope", "private"}
    if previous_level == "private":
        return updated_level == "scope"
    if previous_level != "scope":
        return False
    if updated_level == "private":
        return True
    if updated_level != "scope":
        return False
    previous_groups = {
        str(group_id)
        for group_id in previous.get("group_ids") or []
        if isinstance(group_id, str)
    }
    updated_groups = {
        str(group_id)
        for group_id in updated.get("group_ids") or []
        if isinstance(group_id, str)
    }
    return not previous_groups.issubset(updated_groups)


def apply_control_plane_intent(
    connection: Connection,
    *,
    organization_id: str,
    resource_kind: str,
    resource_id: str,
    revision: int,
    access_level: str,
    group_ids: Sequence[str],
    updated_by_user_id: str = "control_plane",
) -> dict[str, Any]:
    """Atomically apply a newer hosted ACL intent to one local policy.

    The caller owns the surrounding transaction. A stale or already-applied
    revision never rewrites the current policy, which makes retrying a device
    poll safe.
    """

    organization = _required_identifier(organization_id, code="invalid_organization_id")
    kind = _validate_resource_kind(resource_kind)
    identifier = _required_identifier(resource_id, code="invalid_resource_id")
    if not isinstance(revision, int) or isinstance(revision, bool) or revision < 0:
        raise ResourceAccessError("invalid_resource_acl_intent")
    normalized_level, normalized_groups = _validate_policy_values(access_level, group_ids, organization)
    policy = _policy_row(connection, kind, identifier)
    if policy is None:
        raise ResourceAccessError("resource_not_found")
    if _clean_optional_string(policy.get("organization_id")) != organization:
        raise ResourceAccessError("resource_organization_mismatch")

    last_applied = policy.get("last_applied_control_plane_revision")
    last_revision = int(last_applied) if isinstance(last_applied, int) else -1
    policy_revision = int(policy.get("policy_revision") or 0)
    if revision < last_revision or revision < policy_revision:
        return {"status": "stale", "policy": _serialize_policy(connection, policy)}
    if revision == last_revision:
        return {"status": "already_applied", "policy": _serialize_policy(connection, policy)}

    if normalized_groups:
        conflicting_group = connection.execute(
            select(resource_access_groups.c.group_id)
            .where(resource_access_groups.c.group_id.in_(normalized_groups))
            .where(resource_access_groups.c.organization_id != organization)
            .limit(1)
        ).first()
        if conflicting_group is not None:
            raise ResourceAccessError("resource_group_organization_mismatch")

    now = _utc_now_iso()
    connection.execute(
        resource_access_policies.update()
        .where(resource_access_policies.c.resource_kind == kind)
        .where(resource_access_policies.c.resource_id == identifier)
        .values(
            access_level=normalized_level,
            policy_revision=revision,
            last_applied_control_plane_revision=revision,
            updated_by_user_id=_clean_optional_string(updated_by_user_id) or "control_plane",
            updated_at=now,
        )
    )
    _replace_policy_groups(connection, kind, identifier, organization, normalized_groups, now)
    updated = _policy_row(connection, kind, identifier)
    assert updated is not None
    return {"status": "applied", "policy": _serialize_policy(connection, updated)}


def update_local_non_organization_policy(
    connection: Connection,
    *,
    resource_kind: str,
    resource_id: str,
    access_level: str,
    group_ids: Sequence[str] | None,
    updated_by_user_id: str | None,
) -> dict[str, Any]:
    """Update a personal/local policy without touching control-plane revisions."""

    kind = _validate_resource_kind(resource_kind)
    identifier = _required_identifier(resource_id, code="invalid_resource_id")
    policy = _policy_row(connection, kind, identifier)
    if policy is None:
        raise ResourceAccessError("resource_not_found")
    organization = _clean_optional_string(policy.get("organization_id"))
    if organization is not None:
        raise ResourceAccessError("resource_acl_control_plane_required")
    normalized_level, normalized_groups = _validate_policy_values(access_level, group_ids, None)
    now = _utc_now_iso()
    next_revision = int(policy.get("policy_revision") or 0) + 1
    connection.execute(
        resource_access_policies.update()
        .where(resource_access_policies.c.resource_kind == kind)
        .where(resource_access_policies.c.resource_id == identifier)
        .values(
            access_level=normalized_level,
            policy_revision=next_revision,
            updated_by_user_id=_clean_optional_string(updated_by_user_id),
            updated_at=now,
        )
    )
    _replace_policy_groups(connection, kind, identifier, None, normalized_groups, now)
    updated = _policy_row(connection, kind, identifier)
    assert updated is not None
    return _serialize_policy(connection, updated)