agentevo-cloud 0.1.0__py3-none-any.whl

agentevo_cloud/__init__.py

@@ -0,0 +1,452 @@
+"""Agentevo SaaS control plane and managed intelligence APIs."""
+
+from agentevo_cloud.analytics import (
+    FRESHNESS_HORIZON_DAYS as FRESHNESS_HORIZON_DAYS,
+    AnalyticsSummary as AnalyticsSummary,
+    summarize as summarize,
+)
+from agentevo_cloud.app import create_app as create_app
+from agentevo_cloud.config import Settings as Settings
+from agentevo_cloud.db import SCHEMA_VERSION as SCHEMA_VERSION, Database as Database
+from agentevo_cloud.devices import (
+    DEVICE_POLL_INTERVAL as DEVICE_POLL_INTERVAL,
+    KEY_FORMAT_ED25519 as KEY_FORMAT_ED25519,
+    KEY_FORMAT_PEM as KEY_FORMAT_PEM,
+    MAX_KEY_ID_LENGTH as MAX_KEY_ID_LENGTH,
+    Approver as Approver,
+    DeviceAuthorization as DeviceAuthorization,
+    DeviceFlow as DeviceFlow,
+    DevicePoll as DevicePoll,
+    DeviceRecord as DeviceRecord,
+    RepoLink as RepoLink,
+    approve_device_code as approve_device_code,
+    deny_device_code as deny_device_code,
+    exchange_ci_token as exchange_ci_token,
+    find_repo as find_repo,
+    get_device_key as get_device_key,
+    link_repo as link_repo,
+    list_device_keys as list_device_keys,
+    list_devices as list_devices,
+    list_repos as list_repos,
+    poll_device_flow as poll_device_flow,
+    register_device as register_device,
+    revoke_device as revoke_device,
+    start_device_flow as start_device_flow,
+    unlink_repo as unlink_repo,
+)
+from agentevo_cloud.events import (
+    EVENT_BATCH_LIMIT as EVENT_BATCH_LIMIT,
+    EVENT_BATCH_MAX_BYTES as EVENT_BATCH_MAX_BYTES,
+    EVENT_PAYLOAD_MAX_BYTES as EVENT_PAYLOAD_MAX_BYTES,
+    BatchReceipt as BatchReceipt,
+    ingest_batch as ingest_batch,
+    parse_event as parse_event,
+)
+from agentevo_cloud.jobs import (
+    DRIVE_BATCH_LIMIT as DRIVE_BATCH_LIMIT,
+    TERMINAL_STATES as TERMINAL_STATES,
+    DriveReport as DriveReport,
+    Job as Job,
+    JobState as JobState,
+    JobType as JobType,
+    Worker as Worker,
+    WorkerOutcome as WorkerOutcome,
+    cancel_job as cancel_job,
+    create_job as create_job,
+    drive_due as drive_due,
+    get_job as get_job,
+    list_jobs as list_jobs,
+)
+from agentevo_cloud.managed import (
+    ManagedObject as ManagedObject,
+    get_managed as get_managed,
+    index_accepted as index_accepted,
+    latest_managed as latest_managed,
+    list_managed as list_managed,
+)
+from agentevo_cloud.metering import (
+    QUOTA_LIMIT_HEADER as QUOTA_LIMIT_HEADER,
+    QUOTA_REMAINING_HEADER as QUOTA_REMAINING_HEADER,
+    QUOTA_RESET_HEADER as QUOTA_RESET_HEADER,
+    QUOTA_WARNING_HEADER as QUOTA_WARNING_HEADER,
+    RETRY_AFTER_HEADER as RETRY_AFTER_HEADER,
+    Usage as Usage,
+    check_quota as check_quota,
+    check_rate_limit as check_rate_limit,
+    current_cycle as current_cycle,
+    cycle_reset as cycle_reset,
+    is_billable as is_billable,
+    quota_headers as quota_headers,
+    quota_warning as quota_warning,
+    record_billable as record_billable,
+    record_checked as record_checked,
+    retry_after_for as retry_after_for,
+    seconds_until as seconds_until,
+    unrecord_billable as unrecord_billable,
+    usage_for as usage_for,
+)
+from agentevo_cloud.oidc import (
+    CLOCK_SKEW_SECONDS as CLOCK_SKEW_SECONDS,
+    JWKS_TIMEOUT_SECONDS as JWKS_TIMEOUT_SECONDS,
+    JwksFetcher as JwksFetcher,
+    VerifiedClaims as VerifiedClaims,
+    fetch_jwks as fetch_jwks,
+    verify_jwt as verify_jwt,
+)
+from agentevo_cloud.promote import (
+    VerifyTally as VerifyTally,
+    promote_managed as promote_managed,
+)
+from agentevo_cloud.recall import (
+    DEFAULT_MAX_OBJECTS as DEFAULT_MAX_OBJECTS,
+    DEFAULT_MAX_TOKENS as DEFAULT_MAX_TOKENS,
+    MAX_RECALL_OBJECTS as MAX_RECALL_OBJECTS,
+    MAX_RECALL_TOKENS as MAX_RECALL_TOKENS,
+    RecallHit as RecallHit,
+    RecallQuery as RecallQuery,
+    RecallResult as RecallResult,
+    parse_environment as parse_environment,
+    parse_query as parse_query,
+    recall as recall,
+)
+from agentevo_cloud.records import (
+    MAX_AUDIT_LIMIT as MAX_AUDIT_LIMIT,
+    AuditEntry as AuditEntry,
+    IdempotentReplay as IdempotentReplay,
+    audit as audit,
+    idempotency_lookup as idempotency_lookup,
+    idempotency_store as idempotency_store,
+    list_audit as list_audit,
+)
+from agentevo_cloud.revoke import (
+    RevokeResult as RevokeResult,
+    revoke_object as revoke_object,
+)
+from agentevo_cloud.screen import (
+    MAX_EMBEDDING_DIMS as MAX_EMBEDDING_DIMS,
+    RAW_TOP_LEVEL_KEYS as RAW_TOP_LEVEL_KEYS,
+    TOMBSTONE_REASON_MAX as TOMBSTONE_REASON_MAX,
+    assert_no_secrets as assert_no_secrets,
+    check_body_shape as check_body_shape,
+    check_declared_classification as check_declared_classification,
+)
+from agentevo_cloud.sync import (
+    checked_pull_args as checked_pull_args,
+    parse_envelope as parse_envelope,
+    pull_page as pull_page,
+    push_batch as push_batch,
+    store_server_delta as store_server_delta,
+    verify_envelope_signature as verify_envelope_signature,
+)
+from agentevo_cloud.tenants import (
+    ADMIN_ROLE as ADMIN_ROLE,
+    BACKUP_RETENTION_DAYS as BACKUP_RETENTION_DAYS,
+    ELEVATED_SCOPES as ELEVATED_SCOPES,
+    FREE_MONTHLY_QUOTA as FREE_MONTHLY_QUOTA,
+    GRANTABLE_SCOPES as GRANTABLE_SCOPES,
+    MEMBER_ROLE as MEMBER_ROLE,
+    OWNER_ROLE as OWNER_ROLE,
+    PLAN_QUOTAS as PLAN_QUOTAS,
+    PRO_MONTHLY_QUOTA as PRO_MONTHLY_QUOTA,
+    ROLES as ROLES,
+    SYNC_TERMS_VERSION as SYNC_TERMS_VERSION,
+    TEAM_MONTHLY_QUOTA as TEAM_MONTHLY_QUOTA,
+    Entitlements as Entitlements,
+    Membership as Membership,
+    SyncConsent as SyncConsent,
+    SyncMode as SyncMode,
+    Tenant as Tenant,
+    Workspace as Workspace,
+    WorkspaceDeletion as WorkspaceDeletion,
+    WorkspaceExport as WorkspaceExport,
+    add_membership as add_membership,
+    create_tenant as create_tenant,
+    create_workspace as create_workspace,
+    delete_workspace_data as delete_workspace_data,
+    entitlements_for as entitlements_for,
+    export_workspace_data as export_workspace_data,
+    get_membership as get_membership,
+    get_sync_mode as get_sync_mode,
+    get_tenant as get_tenant,
+    list_workspaces as list_workspaces,
+    require_managed as require_managed,
+    require_searchable as require_searchable,
+    searchable_workspaces as searchable_workspaces,
+    set_plan as set_plan,
+    set_sync_mode as set_sync_mode,
+    tenant_managed as tenant_managed,
+)
+from agentevo_cloud.tokens import (
+    ACCESS_KIND as ACCESS_KIND,
+    ACCESS_PREFIX as ACCESS_PREFIX,
+    CI_KIND as CI_KIND,
+    CI_PREFIX as CI_PREFIX,
+    PAT_KIND as PAT_KIND,
+    PAT_PREFIX as PAT_PREFIX,
+    REFRESH_KIND as REFRESH_KIND,
+    REFRESH_PREFIX as REFRESH_PREFIX,
+    IssuedToken as IssuedToken,
+    Principal as Principal,
+    TokenRecord as TokenRecord,
+    hash_token as hash_token,
+    issue_access as issue_access,
+    issue_ci as issue_ci,
+    issue_pat as issue_pat,
+    issue_refresh as issue_refresh,
+    list_tokens as list_tokens,
+    revoke_token as revoke_token,
+    rotate_refresh as rotate_refresh,
+    verify_token as verify_token,
+)
+from agentevo_cloud.webhooks import (
+    EVENT_ID_HEADER as EVENT_ID_HEADER,
+    MAX_DELIVERY_LIMIT as MAX_DELIVERY_LIMIT,
+    MAX_WEBHOOK_CONFIGS as MAX_WEBHOOK_CONFIGS,
+    ROTATION_GRACE_SECONDS as ROTATION_GRACE_SECONDS,
+    SIGNATURE_HEADER as SIGNATURE_HEADER,
+    WEBHOOK_EVENTS as WEBHOOK_EVENTS,
+    WILDCARD_EVENT as WILDCARD_EVENT,
+    Delivery as Delivery,
+    IssuedSecret as IssuedSecret,
+    Sender as Sender,
+    WebhookConfig as WebhookConfig,
+    build_event as build_event,
+    create_config as create_config,
+    deliver_to_config as deliver_to_config,
+    dispatch as dispatch,
+    get_config as get_config,
+    list_configs as list_configs,
+    list_deliveries as list_deliveries,
+    replay_delivery as replay_delivery,
+    revoke_config as revoke_config,
+    rotate_config as rotate_config,
+    sign as sign,
+    urllib_sender as urllib_sender,
+    verify_signature as verify_signature,
+    verify_with_rotation as verify_with_rotation,
+)
+from agentevo_cloud.workers import (
+    DEFAULT_COMPILE_PROJECT as DEFAULT_COMPILE_PROJECT,
+    VERIFICATION_VALIDITY_DAYS as VERIFICATION_VALIDITY_DAYS,
+    WORKERS as WORKERS,
+    compile_experiences_worker as compile_experiences_worker,
+    compile_workflow_worker as compile_workflow_worker,
+    ensure_workspace as ensure_workspace,
+    parse_bindings as parse_bindings,
+    parse_canary_steps as parse_canary_steps,
+    parse_fallbacks as parse_fallbacks,
+    parse_required_str as parse_required_str,
+    parse_rollback as parse_rollback,
+    parse_skill_refs as parse_skill_refs,
+    verify_worker as verify_worker,
+)
+
+__all__ = [
+    "ACCESS_KIND",
+    "ACCESS_PREFIX",
+    "ADMIN_ROLE",
+    "BACKUP_RETENTION_DAYS",
+    "CI_KIND",
+    "CI_PREFIX",
+    "CLOCK_SKEW_SECONDS",
+    "DEFAULT_COMPILE_PROJECT",
+    "DEFAULT_MAX_OBJECTS",
+    "DEFAULT_MAX_TOKENS",
+    "DEVICE_POLL_INTERVAL",
+    "DRIVE_BATCH_LIMIT",
+    "ELEVATED_SCOPES",
+    "EVENT_BATCH_LIMIT",
+    "EVENT_BATCH_MAX_BYTES",
+    "EVENT_ID_HEADER",
+    "EVENT_PAYLOAD_MAX_BYTES",
+    "FREE_MONTHLY_QUOTA",
+    "FRESHNESS_HORIZON_DAYS",
+    "GRANTABLE_SCOPES",
+    "JWKS_TIMEOUT_SECONDS",
+    "KEY_FORMAT_ED25519",
+    "KEY_FORMAT_PEM",
+    "MAX_AUDIT_LIMIT",
+    "MAX_DELIVERY_LIMIT",
+    "MAX_EMBEDDING_DIMS",
+    "MAX_KEY_ID_LENGTH",
+    "MAX_RECALL_OBJECTS",
+    "MAX_RECALL_TOKENS",
+    "MAX_WEBHOOK_CONFIGS",
+    "MEMBER_ROLE",
+    "OWNER_ROLE",
+    "PAT_KIND",
+    "PAT_PREFIX",
+    "PLAN_QUOTAS",
+    "PRO_MONTHLY_QUOTA",
+    "QUOTA_LIMIT_HEADER",
+    "QUOTA_REMAINING_HEADER",
+    "QUOTA_RESET_HEADER",
+    "QUOTA_WARNING_HEADER",
+    "RAW_TOP_LEVEL_KEYS",
+    "REFRESH_KIND",
+    "REFRESH_PREFIX",
+    "RETRY_AFTER_HEADER",
+    "ROLES",
+    "ROTATION_GRACE_SECONDS",
+    "SCHEMA_VERSION",
+    "SIGNATURE_HEADER",
+    "SYNC_TERMS_VERSION",
+    "TEAM_MONTHLY_QUOTA",
+    "TERMINAL_STATES",
+    "TOMBSTONE_REASON_MAX",
+    "VERIFICATION_VALIDITY_DAYS",
+    "WEBHOOK_EVENTS",
+    "WILDCARD_EVENT",
+    "WORKERS",
+    "AnalyticsSummary",
+    "Approver",
+    "AuditEntry",
+    "BatchReceipt",
+    "Database",
+    "Delivery",
+    "DeviceAuthorization",
+    "DeviceFlow",
+    "DevicePoll",
+    "DeviceRecord",
+    "DriveReport",
+    "Entitlements",
+    "IdempotentReplay",
+    "IssuedSecret",
+    "IssuedToken",
+    "Job",
+    "JobState",
+    "JobType",
+    "JwksFetcher",
+    "ManagedObject",
+    "Membership",
+    "Principal",
+    "RecallHit",
+    "RecallQuery",
+    "RecallResult",
+    "RepoLink",
+    "RevokeResult",
+    "Sender",
+    "Settings",
+    "SyncConsent",
+    "SyncMode",
+    "Tenant",
+    "TokenRecord",
+    "Usage",
+    "VerifiedClaims",
+    "VerifyTally",
+    "WebhookConfig",
+    "Worker",
+    "WorkerOutcome",
+    "Workspace",
+    "WorkspaceDeletion",
+    "WorkspaceExport",
+    "add_membership",
+    "approve_device_code",
+    "assert_no_secrets",
+    "audit",
+    "build_event",
+    "cancel_job",
+    "check_body_shape",
+    "check_declared_classification",
+    "check_quota",
+    "check_rate_limit",
+    "checked_pull_args",
+    "compile_experiences_worker",
+    "compile_workflow_worker",
+    "create_app",
+    "create_config",
+    "create_job",
+    "create_tenant",
+    "create_workspace",
+    "current_cycle",
+    "cycle_reset",
+    "delete_workspace_data",
+    "deliver_to_config",
+    "deny_device_code",
+    "dispatch",
+    "drive_due",
+    "ensure_workspace",
+    "entitlements_for",
+    "exchange_ci_token",
+    "export_workspace_data",
+    "fetch_jwks",
+    "find_repo",
+    "get_config",
+    "get_device_key",
+    "get_job",
+    "get_managed",
+    "get_membership",
+    "get_sync_mode",
+    "get_tenant",
+    "hash_token",
+    "idempotency_lookup",
+    "idempotency_store",
+    "index_accepted",
+    "ingest_batch",
+    "is_billable",
+    "issue_access",
+    "issue_ci",
+    "issue_pat",
+    "issue_refresh",
+    "latest_managed",
+    "link_repo",
+    "list_audit",
+    "list_configs",
+    "list_deliveries",
+    "list_device_keys",
+    "list_devices",
+    "list_jobs",
+    "list_managed",
+    "list_repos",
+    "list_tokens",
+    "list_workspaces",
+    "parse_bindings",
+    "parse_canary_steps",
+    "parse_envelope",
+    "parse_environment",
+    "parse_event",
+    "parse_fallbacks",
+    "parse_query",
+    "parse_required_str",
+    "parse_rollback",
+    "parse_skill_refs",
+    "poll_device_flow",
+    "promote_managed",
+    "pull_page",
+    "push_batch",
+    "quota_headers",
+    "quota_warning",
+    "recall",
+    "record_billable",
+    "record_checked",
+    "register_device",
+    "replay_delivery",
+    "require_managed",
+    "require_searchable",
+    "retry_after_for",
+    "revoke_config",
+    "revoke_device",
+    "revoke_object",
+    "revoke_token",
+    "rotate_config",
+    "rotate_refresh",
+    "searchable_workspaces",
+    "seconds_until",
+    "set_plan",
+    "set_sync_mode",
+    "sign",
+    "start_device_flow",
+    "store_server_delta",
+    "summarize",
+    "tenant_managed",
+    "unlink_repo",
+    "unrecord_billable",
+    "urllib_sender",
+    "usage_for",
+    "verify_envelope_signature",
+    "verify_jwt",
+    "verify_signature",
+    "verify_token",
+    "verify_with_rotation",
+    "verify_worker",
+]

agentevo_cloud/analytics.py

@@ -0,0 +1,238 @@
+"""Team analytics: tenant-scoped aggregates over the managed index.
+
+Spec grounding: PRD §15 ("record improved execution metrics"), PRD §16
+Measurement ("Baseline vs learned-run evaluation visible in dashboard/API"),
+and BRD ("outcome analytics must all be real"). This endpoint reports only
+what the cloud stores: managed-object registry state, event outcomes,
+async-job outcomes, and verification freshness. It serves counts, never
+bodies.
+
+Spec-silent choices: the route is billable (the metering exception list is
+closed and analytics is not on it); any tenant role may read it (aggregates
+carry no object bodies); the ``workspace`` filter scopes the object and
+verification sections while events and jobs stay tenant-wide (those rows
+are not workspace-attributed), labeled honestly in ``tenant_wide``.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from agentevo_core.errors import AgentevoError, ErrorCode
+
+#: Freshness horizon: verified objects expiring within this window count as
+#: "expiring" rather than "fresh".
+FRESHNESS_HORIZON_DAYS = 7
+
+
+@dataclass(frozen=True)
+class AnalyticsSummary:
+    """One analytics snapshot (counts only, no object bodies)."""
+
+    tenant_id: str
+    workspace: str | None
+    generated_at: str
+    objects_total: int
+    objects_versions: int
+    objects_by_state: dict[str, int]
+    objects_by_type: dict[str, int]
+    objects_by_risk: dict[str, int]
+    objects_tombstoned: int
+    verification_fresh: int
+    verification_expiring: int
+    verification_expired: int
+    verification_never: int
+    events_total: int
+    events_by_type: dict[str, int]
+    jobs_total: int
+    jobs_by_state: dict[str, int]
+    jobs_by_type: dict[str, int]
+    tenant_wide: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        """JSON shape served by GET /v1/analytics/summary."""
+        return {
+            "tenant_id": self.tenant_id,
+            "workspace": self.workspace,
+            "generated_at": self.generated_at,
+            "objects": {
+                "total": self.objects_total,
+                "versions": self.objects_versions,
+                "by_state": self.objects_by_state,
+                "by_type": self.objects_by_type,
+                "by_risk": self.objects_by_risk,
+                "tombstoned": self.objects_tombstoned,
+            },
+            "verification": {
+                "fresh": self.verification_fresh,
+                "expiring_7d": self.verification_expiring,
+                "expired": self.verification_expired,
+                "never": self.verification_never,
+            },
+            "events": {"total": self.events_total, "by_type": self.events_by_type},
+            "jobs": {
+                "total": self.jobs_total,
+                "by_state": self.jobs_by_state,
+                "by_type": self.jobs_by_type,
+            },
+            "tenant_wide": list(self.tenant_wide),
+        }
+
+
+def summarize(
+    conn: sqlite3.Connection,
+    tenant_id: str,
+    *,
+    workspace: str | None = None,
+    workspaces: tuple[str, ...] = (),
+    now: datetime | None = None,
+) -> AnalyticsSummary:
+    """Aggregate one tenant's managed-index counts (404 on unknown workspace).
+
+    An explicit ``workspace`` scopes the object/verification sections to it;
+    otherwise token ``workspaces`` scope them when set. Events and jobs are
+    always tenant-wide (their rows carry no workspace).
+    """
+    moment = now or datetime.now(UTC)
+    slugs: tuple[str, ...] | None
+    if workspace is not None:
+        row = conn.execute(
+            "SELECT 1 FROM workspaces WHERE tenant_id = ? AND slug = ?",
+            (tenant_id, workspace),
+        ).fetchone()
+        if row is None:
+            raise AgentevoError(ErrorCode.NOT_FOUND, f"unknown workspace: {workspace}", {})
+        slugs = (workspace,)
+    elif workspaces:
+        slugs = workspaces
+    else:
+        slugs = None
+    latest = _latest_objects(conn, tenant_id, slugs)
+    by_state: dict[str, int] = {}
+    by_type: dict[str, int] = {}
+    by_risk: dict[str, int] = {}
+    fresh = expiring = expired = never = 0
+    horizon = moment + timedelta(days=FRESHNESS_HORIZON_DAYS)
+    for item in latest:
+        by_state[item["state"]] = by_state.get(item["state"], 0) + 1
+        by_type[item["object_type"]] = by_type.get(item["object_type"], 0) + 1
+        by_risk[item["risk_class"]] = by_risk.get(item["risk_class"], 0) + 1
+        bucket = _freshness_bucket(item["verified_at"], item["valid_until"], moment, horizon)
+        if bucket == "fresh":
+            fresh += 1
+        elif bucket == "expiring":
+            expiring += 1
+        elif bucket == "expired":
+            expired += 1
+        else:
+            never += 1
+    event_rows = conn.execute(
+        "SELECT event_type, COUNT(*) AS total FROM managed_events"
+        " WHERE tenant_id = ? GROUP BY event_type ORDER BY event_type ASC",
+        (tenant_id,),
+    ).fetchall()
+    job_rows = conn.execute(
+        "SELECT job_type, state, COUNT(*) AS total FROM jobs"
+        " WHERE tenant_id = ? GROUP BY job_type, state",
+        (tenant_id,),
+    ).fetchall()
+    jobs_by_state: dict[str, int] = {}
+    jobs_by_type: dict[str, int] = {}
+    jobs_total = 0
+    for row in job_rows:
+        jobs_by_state[row["state"]] = jobs_by_state.get(row["state"], 0) + row["total"]
+        jobs_by_type[row["job_type"]] = jobs_by_type.get(row["job_type"], 0) + row["total"]
+        jobs_total += row["total"]
+    return AnalyticsSummary(
+        tenant_id=tenant_id,
+        workspace=workspace,
+        generated_at=moment.isoformat(),
+        objects_total=len(latest),
+        objects_versions=_count_versions(conn, tenant_id, slugs),
+        objects_by_state=by_state,
+        objects_by_type=by_type,
+        objects_by_risk=by_risk,
+        objects_tombstoned=_count_tombstoned(conn, tenant_id, slugs),
+        verification_fresh=fresh,
+        verification_expiring=expiring,
+        verification_expired=expired,
+        verification_never=never,
+        events_total=sum(row["total"] for row in event_rows),
+        events_by_type={row["event_type"]: row["total"] for row in event_rows},
+        jobs_total=jobs_total,
+        jobs_by_state=jobs_by_state,
+        jobs_by_type=jobs_by_type,
+        tenant_wide=("events", "jobs") if workspace is not None else (),
+    )
+
+
+def _latest_objects(
+    conn: sqlite3.Connection, tenant_id: str, slugs: tuple[str, ...] | None
+) -> list[dict[str, Any]]:
+    """Latest kind=object version per object_id (the live registry view)."""
+    clauses = ["tenant_id = ?", "kind = 'object'"]
+    params: list[str] = [tenant_id]
+    if slugs is not None:
+        placeholders = ", ".join("?" for _ in slugs)
+        clauses.append(f"workspace_id IN ({placeholders})")
+        params.extend(slugs)
+    where = " AND ".join(clauses)
+    query = (
+        "SELECT m.state, m.object_type, m.risk_class, m.verified_at, m.valid_until"  # noqa: S608
+        " FROM managed_objects AS m JOIN (SELECT object_id, MAX(version) AS version"
+        f" FROM managed_objects WHERE {where} GROUP BY object_id) AS latest"
+        " ON m.object_id = latest.object_id AND m.version = latest.version"
+        " WHERE m.tenant_id = ? AND m.kind = 'object'"
+    )
+    rows = conn.execute(query, (*params, tenant_id)).fetchall()
+    return [dict(row) for row in rows]
+
+
+def _count_versions(conn: sqlite3.Connection, tenant_id: str, slugs: tuple[str, ...] | None) -> int:
+    """Stored kind=object versions (every version, not just latest)."""
+    clauses = ["tenant_id = ?", "kind = 'object'"]
+    params: list[str] = [tenant_id]
+    if slugs is not None:
+        placeholders = ", ".join("?" for _ in slugs)
+        clauses.append(f"workspace_id IN ({placeholders})")
+        params.extend(slugs)
+    query = "SELECT COUNT(*) AS total FROM managed_objects WHERE " + " AND ".join(clauses)  # noqa: S608
+    row = conn.execute(query, params).fetchone()
+    return int(row["total"])
+
+
+def _count_tombstoned(
+    conn: sqlite3.Connection, tenant_id: str, slugs: tuple[str, ...] | None
+) -> int:
+    """Distinct object ids carrying a tombstone row."""
+    clauses = ["tenant_id = ?", "kind = 'tombstone'"]
+    params: list[str] = [tenant_id]
+    if slugs is not None:
+        placeholders = ", ".join("?" for _ in slugs)
+        clauses.append(f"workspace_id IN ({placeholders})")
+        params.extend(slugs)
+    query = (
+        "SELECT COUNT(DISTINCT object_id) AS total FROM managed_objects WHERE "  # noqa: S608
+        + " AND ".join(clauses)
+    )
+    row = conn.execute(query, params).fetchone()
+    return int(row["total"])
+
+
+def _freshness_bucket(
+    verified_at: str | None, valid_until: str | None, moment: datetime, horizon: datetime
+) -> str:
+    """Freshness bucket mirroring recall's validity gate (usable ⟺ end > now)."""
+    if verified_at is None:
+        return "never"
+    if valid_until is None:
+        return "fresh"
+    end = datetime.fromisoformat(valid_until)
+    if end <= moment:
+        return "expired"
+    if end <= horizon:
+        return "expiring"
+    return "fresh"