Skip to content

teng-lin/notebooklm-py

notebooklm

Verified

Install, authenticate, troubleshoot, and operate Gemini Notebook through the notebooklm-py CLI or typed async Python API. Use for notebook and source management, grounded chat and research, and artifact generation or download when the user mentions Gemini Notebook, notebooklm-py, the notebooklm CLI, or its Python API. Do not use for the generic Gemini API or unrelated content creation.

FileKindSize
SKILL.mdskill md16.0 KB
examples/bulk-import.pyscript3.4 KB
examples/chat.pyscript6.9 KB
examples/notes.pyscript9.8 KB
examples/quickstart.pyscript2.3 KB
examples/refresh_browser_cookies.pyscript2.9 KB
examples/research-to-podcast.pyscript3.2 KB
examples/video.pyscript5.9 KB
scripts/__init__.pyscript73 B
scripts/_ci_e2e_notebooks.pyscript19.0 KB
scripts/_ci_progress.pyscript2.5 KB
scripts/_ci_rpc_progress.pyscript7.5 KB
scripts/_live_auth_scenarios/__init__.pyscript2.6 KB
scripts/_live_auth_scenarios/_contract.pyscript1.9 KB
scripts/_live_auth_scenarios/browser_refresh.pyscript3.1 KB
scripts/_live_auth_scenarios/crash_safe_writer.pyscript1.9 KB
scripts/_live_auth_scenarios/master_token_recovery.pyscript3.3 KB
scripts/_live_auth_scenarios/mcp_recovery.pyscript3.0 KB
scripts/_live_auth_scenarios/rest_recovery.pyscript5.9 KB
scripts/_live_auth_scenarios/sibling_concurrent_reload.pyscript3.9 KB
scripts/_live_auth_scenarios/storage_reload.pyscript2.9 KB
scripts/_onetime_rescrub_cookies.pyscript6.6 KB
scripts/_onetime_retarget_cassette_hosts.pyscript8.5 KB
scripts/_strip_audit_refs.pyscript15.9 KB
scripts/_tracked_files.pyscript872 B
scripts/aggregate_ci_e2e_outcomes.pyscript10.8 KB
scripts/android_grpc_canary.pyscript26.6 KB
scripts/api-compat-allowlist.jsonconfig163 B
scripts/audit_auth_import_graph.pyscript7.5 KB
scripts/audit_auth_patch_sites.pyscript83.6 KB
scripts/audit_auth_shared_mutations.pyscript41.7 KB
scripts/audit_backend_coupling.pyscript32.8 KB
scripts/audit_public_api_compat.pyscript47.4 KB
scripts/audit_test_suite.pyscript10.7 KB
scripts/capture_mobile_grpc.jsscript5.1 KB
scripts/capture_rpc_registry.pyscript44.5 KB
scripts/check_action_pinning.pyscript6.7 KB
scripts/check_auth_behavior_scenario_policy.pyscript37.1 KB
scripts/check_auth_coverage_delta.pyscript23.2 KB
scripts/check_auth_lifecycle_cleanup_policy.pyscript11.7 KB
scripts/check_base_wheel.pyscript6.3 KB
scripts/check_ci_install_parity.pyscript8.8 KB
scripts/check_claude_md_freshness.pyscript8.0 KB
scripts/check_coverage_thresholds.pyscript8.4 KB
scripts/check_deprecation_targets.pyscript33.1 KB
scripts/check_docs_module_refs.pyscript14.4 KB
scripts/check_rpc_health.pyscript112.0 KB
scripts/check_workflow_permissions.pyscript5.3 KB
scripts/check_workflow_secret_gates.pyscript40.4 KB
scripts/decode_mobile_grpc.pyscript7.2 KB
scripts/diagnose_get_notebook.pyscript9.1 KB
scripts/extract_blutter_grpc_signatures.pyscript7.6 KB
scripts/live_auth_matrix.pyscript40.2 KB
scripts/manage_ci_e2e_notebooks.pyscript67.4 KB
scripts/materialize_ci_auth.pyscript8.0 KB
scripts/mcp_live_smoke.pyexecutablescript224 B
scripts/parse_pbenums.pyscript8.6 KB
scripts/parse_pbschema.pyscript11.8 KB
scripts/regen_baselines.pyscript2.7 KB
scripts/regenerate_android_protos.pyscript16.3 KB
scripts/rescrub-cassettes.pyscript13.3 KB
scripts/scrub_rpc_har.pyscript9.4 KB
scripts/select_ci_account.pyscript4.8 KB
scripts/stress_fault_server.pyscript20.6 KB
scripts/test_taxonomy_inventory.pyscript16.1 KB
scripts/verify_ci_artifacts.pyscript35.3 KB

scripts/check_auth_behavior_scenario_policy.py

View on GitHub
#!/usr/bin/env python3
"""Collect and validate authored base/head auth behavior scenario evidence."""

from __future__ import annotations

import argparse
import ast
import contextlib
import inspect
import io
import json
import os
import subprocess
import sys
from collections import Counter
from pathlib import Path, PurePosixPath
from typing import Any, cast

REPO_ROOT = Path(__file__).resolve().parent.parent
DEFAULT_POLICY = REPO_ROOT / "tests/fixtures/policies/auth_behavior_scenarios.json"
NON_PASSING_EVIDENCE_MARKERS = {"repo_lint", "reality", "skip", "skipif", "xfail"}
LIFECYCLE_POLICY = REPO_ROOT / "tests/fixtures/policies/auth_lifecycle_cleanup.json"
CONTRACT_TAGS = {
    "cancellation",
    "compatibility_identity",
    "compatibility_signature",
    "concurrency",
    "exception",
    "ordering",
    "persistence_bytes",
    "redaction_scrubbing",
    "result",
    "traceback_cause",
}
MODULE_MUTATION_FIELDS = {
    "package",
    "module",
    "attribute",
    "idiom",
    "path",
    "owner_qualname",
    "owner_kind",
    "count",
}
SHARED_MUTATION_FIELDS = {
    "package",
    "owner",
    "attribute",
    "idiom",
    "path",
    "owner_qualname",
    "owner_kind",
    "count",
}


class PolicyError(RuntimeError):
    pass


def load_json(path: Path) -> dict[str, Any]:
    value = json.loads(path.read_text(encoding="utf-8"))
    if not isinstance(value, dict):
        raise PolicyError(f"{path}: expected an object")
    return value


def _canonical(nodeid: str) -> str:
    return nodeid.split("[", 1)[0]


def _function_scope_nodes(
    node: ast.FunctionDef | ast.AsyncFunctionDef,
) -> list[ast.AST]:
    """Walk one function body without attributing nested bodies to it."""
    result: list[ast.AST] = []

    def walk(current: ast.AST) -> None:
        result.append(current)
        for child in ast.iter_child_nodes(current):
            if isinstance(
                child,
                ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.Lambda,
            ):
                result.append(child)
            else:
                walk(child)

    for statement in node.body:
        walk(statement)
    return result


def _static_helper_consumers(
    workspace: Path, items: list[dict[str, Any]]
) -> tuple[dict[str, list[str]], list[str]]:
    consumers: dict[str, set[str]] = {}
    unresolved: set[str] = set()
    concrete_by_canonical: dict[str, set[str]] = {}
    for item in items:
        concrete_by_canonical.setdefault(item["canonical_node"], set()).add(item["nodeid"])
    for path in sorted((workspace / "tests").rglob("*.py")):
        try:
            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
        except (OSError, SyntaxError):
            continue

        class Visitor(ast.NodeVisitor):
            def __init__(self) -> None:
                self.functions: dict[str, ast.FunctionDef | ast.AsyncFunctionDef] = {}
                self.stack: list[str] = []

            def visit_ClassDef(self, node: ast.ClassDef) -> None:
                self.stack.append(node.name)
                self.generic_visit(node)
                self.stack.pop()

            def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
                qualname = ".".join((*self.stack, node.name))
                self.functions[qualname] = node
                self.stack.append(node.name)
                self.generic_visit(node)
                self.stack.pop()

            def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
                qualname = ".".join((*self.stack, node.name))
                self.functions[qualname] = node
                self.stack.append(node.name)
                self.generic_visit(node)
                self.stack.pop()

        visitor = Visitor()
        visitor.visit(tree)
        functions = visitor.functions
        calls: dict[str, set[str]] = {}
        file_unresolved: set[str] = set()
        by_leaf: dict[str, set[str]] = {}
        for name in functions:
            by_leaf.setdefault(name.rsplit(".", 1)[-1], set()).add(name)
        helper_names = {
            name for name in functions if not name.rsplit(".", 1)[-1].startswith("test_")
        }
        for name, node in functions.items():
            scoped_nodes = _function_scope_nodes(node)
            scoped_ids = {id(child) for child in scoped_nodes}
            parents = {
                id(child): parent
                for parent in scoped_nodes
                for child in ast.iter_child_nodes(parent)
                if id(child) in scoped_ids
            }
            calls[name] = set()
            for child in scoped_nodes:
                if isinstance(child, ast.Call):
                    candidates: set[str] = set()
                    opaque_candidates: set[str] = set()
                    if isinstance(child.func, ast.Subscript):
                        # ``globals()[name]()``, registries, and other dynamic
                        # dispatch can name any helper in the file.
                        opaque_candidates = helper_names
                    elif (
                        isinstance(child.func, ast.Call)
                        and isinstance(child.func.func, ast.Name)
                        and child.func.func.id == "getattr"
                    ):
                        attribute = (
                            child.func.args[1]
                            if len(child.func.args) > 1
                            else next(
                                (
                                    keyword.value
                                    for keyword in child.func.keywords
                                    if keyword.arg == "name"
                                ),
                                None,
                            )
                        )
                        if isinstance(attribute, ast.Constant) and isinstance(attribute.value, str):
                            opaque_candidates = by_leaf.get(attribute.value, set())
                        else:
                            opaque_candidates = helper_names
                    file_unresolved.update(opaque_candidates)
                    if isinstance(child.func, ast.Name):
                        candidates = by_leaf.get(child.func.id, set())
                    elif (
                        isinstance(child.func, ast.Attribute)
                        and isinstance(child.func.value, ast.Name)
                        and child.func.value.id in {"self", "cls"}
                    ):
                        class_name = name.rpartition(".")[0]
                        candidate = f"{class_name}.{child.func.attr}" if class_name else ""
                        candidates = {candidate} if candidate in functions else set()
                    if len(candidates) == 1:
                        calls[name].update(candidates)
                    elif candidates:
                        file_unresolved.update(candidates)
                if not isinstance(child, ast.Name) or not isinstance(child.ctx, ast.Load):
                    continue
                candidates = by_leaf.get(child.id, set())
                parent = parents.get(id(child))
                direct_call = isinstance(parent, ast.Call) and parent.func is child
                if candidates and (not direct_call or len(candidates) != 1):
                    file_unresolved.update(candidates)
        rel = path.relative_to(workspace).as_posix()
        test_roots = [name for name in functions if name.rsplit(".", 1)[-1].startswith("test_")]
        for helper in functions:
            reached: set[str] = set()
            for test_name in test_roots:
                pending = [test_name]
                seen: set[str] = set()
                while pending:
                    current = pending.pop()
                    if current in seen:
                        continue
                    seen.add(current)
                    if helper in calls.get(current, set()):
                        reached.add(test_name)
                    pending.extend(calls.get(current, set()))
            nodes: set[str] = set()
            for test_name in reached:
                canonical = f"{rel}::" + test_name.replace(".", "::")
                nodes.update(concrete_by_canonical.get(canonical, set()))
            consumers[f"{rel}::{helper}"] = nodes
        unresolved.update(f"{rel}::{name}" for name in file_unresolved)
    return (
        {key: sorted(value) for key, value in sorted(consumers.items())},
        sorted(unresolved),
    )


def collect_workspace(workspace: Path) -> dict[str, Any]:
    """Collect concrete/canonical nodes and full fixture closure with pytest."""

    workspace = workspace.resolve()
    items: list[dict[str, Any]] = []

    class Collector:
        @staticmethod
        def pytest_collection_finish(session: Any) -> None:
            for item in session.items:
                original_name = getattr(item, "originalname", None)
                canonical_node = (
                    f"{item.parent.nodeid}::{original_name}"
                    if isinstance(original_name, str) and original_name
                    else _canonical(item.nodeid)
                )
                fixtures: list[str] = []
                for name in set(item.fixturenames):
                    definitions = item._fixtureinfo.name2fixturedefs.get(name) or ()
                    if not definitions:
                        continue
                    function = definitions[-1].func
                    source = inspect.getsourcefile(function)
                    if source is None:
                        continue
                    try:
                        rel = Path(source).resolve().relative_to(workspace).as_posix()
                    except ValueError:
                        continue
                    qualname = function.__qualname__.replace(".<locals>.", ".")
                    fixtures.append(f"{rel}::{qualname}")
                items.append(
                    {
                        "nodeid": item.nodeid,
                        "canonical_node": canonical_node,
                        "fixtures": sorted(fixtures),
                        "non_passing_markers": sorted(
                            {
                                marker.name
                                for marker in item.iter_markers()
                                if marker.name in NON_PASSING_EVIDENCE_MARKERS
                            }
                        ),
                    }
                )

    before = Path.cwd()
    try:
        os.chdir(workspace)
        import pytest

        captured = io.StringIO()
        with contextlib.redirect_stdout(captured), contextlib.redirect_stderr(captured):
            status = pytest.main(["--collect-only", "-q", "tests"], plugins=[Collector()])
    finally:
        os.chdir(before)
    if status != 0:
        tail = captured.getvalue()[-4000:]
        raise PolicyError(f"pytest collection failed in {workspace}: exit {status}\n{tail}")
    fixture_consumers: dict[str, list[str]] = {}
    for item in items:
        for fixture in item["fixtures"]:
            fixture_consumers.setdefault(fixture, []).append(item["nodeid"])
    helper_consumers, unresolved_helpers = _static_helper_consumers(workspace, items)
    return {
        "version": 1,
        "workspace": str(workspace),
        "items": sorted(items, key=lambda item: item["nodeid"]),
        "fixture_consumers": {
            name: sorted(nodes) for name, nodes in sorted(fixture_consumers.items())
        },
        "helper_consumers": helper_consumers,
        "unresolved_helpers": unresolved_helpers,
    }


def _expand(selectors: list[str], collection: dict[str, Any], label: str) -> set[str]:
    items = collection.get("items", [])
    expanded: set[str] = set()
    for selector in selectors:
        if any(token in selector for token in ("*", "?", "[!")) or selector.endswith("::"):
            raise PolicyError(f"{label}: wildcards/module selectors are forbidden: {selector}")
        matches = {
            item["nodeid"]
            for item in items
            if item["nodeid"] == selector or item["canonical_node"] == selector
        }
        if not matches:
            raise PolicyError(f"{label}: selector collected no nodes: {selector}")
        if expanded & matches:
            raise PolicyError(f"{label}: duplicate selector coverage: {selector}")
        expanded.update(matches)
    return expanded


def _is_normalized_affected_path(value: Any) -> bool:
    if not isinstance(value, str) or any(
        token in value for token in ("*", "?", "[", "]", "{", "}", "\\")
    ):
        return False
    path = PurePosixPath(value)
    return (
        value == path.as_posix()
        and path.parts[:2] == ("src", "notebooklm")
        and len(path.parts) >= 3
        and path.suffix == ".py"
        and "." not in path.parts
        and ".." not in path.parts
    )


def _validate_mutation(row: Any, label: str) -> dict[str, Any]:
    if not isinstance(row, dict) or set(row) not in {
        frozenset(MODULE_MUTATION_FIELDS),
        frozenset(SHARED_MUTATION_FIELDS),
    }:
        raise PolicyError(f"{label}: base mutation is not an exact joint projection row")
    if row["owner_kind"] not in {"test", "fixture", "helper"}:
        raise PolicyError(f"{label}: invalid mutation owner kind")
    if not isinstance(row["count"], int) or isinstance(row["count"], bool) or row["count"] < 1:
        raise PolicyError(f"{label}: mutation count must be a positive integer")
    return row


def _mutation_identity(row: dict[str, Any]) -> tuple[Any, ...]:
    fields = MODULE_MUTATION_FIELDS if "module" in row else SHARED_MUTATION_FIELDS
    return tuple(row[field] for field in sorted(fields - {"count"}))


def _unresolved_helper_mutation_key(row: dict[str, Any]) -> tuple[Any, ...]:
    target_field = "module" if "module" in row else "owner"
    return (
        row["package"],
        target_field,
        row[target_field],
        row["attribute"],
        row["idiom"],
        row["path"],
        row["owner_qualname"],
        row["owner_kind"],
        row["count"],
    )


# These are the complete unresolved helper rows in the pinned integration-base
# decrease ledger. Their scenario selectors and concrete mappings remain exact,
# and the global mutation counter still requires each full row and count. This
# exception does not authorize any other unresolved helper identity.
_PINNED_UNRESOLVED_HELPER_MUTATIONS: frozenset[tuple[Any, ...]] = frozenset(
    {
        (
            "notebooklm._auth",
            "module",
            "profile_store",
            "_STORAGE_LOCKS",
            "monkeypatch.setattr",
            "tests/unit/test_storage_writer.py",
            "_patch_lock_unavailable",
            "helper",
            1,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.profile_store.ProfileStore",
            "read_master_token",
            "patch.object",
            "tests/unit/test_auth_master_token_bootstrap.py",
            "test_public_malformed_projection_preserves_ordinary_context.invoke",
            "helper",
            1,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.single_flight.SingleFlight.process_default()",
            "claim",
            "gateway-method-or-unknown",
            "tests/unit/test_refresh_lock_registry.py",
            "TestDoubleCancelDoesNotDetonateBridge.test_second_cancel_while_pending_preserves_bridge_and_siblings._run",
            "helper",
            1,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.single_flight.SingleFlight.process_default()",
            "claim",
            "gateway-method-or-unknown",
            "tests/unit/test_refresh_lock_registry.py",
            "TestPromptPopRetention.test_registry_does_not_accumulate_across_cycles._run",
            "helper",
            1,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.single_flight.SingleFlight.process_default()",
            "claim",
            "gateway-method-or-unknown",
            "tests/unit/test_auth_headless_reauth.py",
            "test_single_flight_is_unreachable_from_the_sync_drive_entry._drive_in_worker_thread._claim_from_worker",
            "helper",
            1,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.single_flight.SingleFlight.process_default()",
            "claim",
            "gateway-method-or-unknown",
            "tests/unit/test_refresh_lock_registry.py",
            "TestFlightClaimIdentity.test_distinct_keys_get_distinct_flights._run",
            "helper",
            2,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.single_flight.SingleFlight.process_default()",
            "claim",
            "gateway-method-or-unknown",
            "tests/unit/test_refresh_lock_registry.py",
            "TestFlightClaimIdentity.test_second_claim_same_key_follows_leader._run",
            "helper",
            2,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.single_flight.SingleFlight.process_default()",
            "claim",
            "gateway-method-or-unknown",
            "tests/unit/test_refresh_lock_registry.py",
            "TestFlightClaimIdentity.test_settled_flight_is_overwritable_by_next_leader._run",
            "helper",
            2,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.single_flight.SingleFlight.process_default()",
            "claim_if_epoch_current",
            "gateway-method-or-unknown",
            "tests/unit/test_refresh_lock_registry.py",
            "TestClaimIfEpochCurrent.test_claims_when_epoch_unchanged._run",
            "helper",
            1,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.single_flight.SingleFlight.process_default()",
            "claim_if_epoch_current",
            "gateway-method-or-unknown",
            "tests/unit/test_refresh_lock_registry.py",
            "TestClaimIfEpochCurrent.test_skips_when_epoch_already_advanced._run",
            "helper",
            1,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.single_flight.SingleFlight.process_default()",
            "note_success",
            "gateway-method-or-unknown",
            "tests/unit/test_refresh_lock_registry.py",
            "TestClaimIfEpochCurrent.test_skips_when_epoch_already_advanced._run",
            "helper",
            1,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.storage_lock.StorageLockManager",
            "process_default",
            "monkeypatch.setattr",
            "tests/unit/test_storage_writer.py",
            "_patch_master_token_lock_unavailable",
            "helper",
            1,
        ),
        (
            "notebooklm._auth",
            "owner",
            "notebooklm._auth.profile_migration.LegacyPromotionScheduler.process_default()",
            "schedule",
            "gateway-method-or-unknown",
            "tests/unit/test_auth_account_promotion.py",
            "TestRetryableSingleFlight.test_concurrent_reads_of_one_profile_promote_exactly_once._read",
            "helper",
            1,
        ),
    }
)


_PINNED_UNRESOLVED_HELPER_CONSUMERS: dict[tuple[str, str], frozenset[str]] = {
    ("tests/unit/test_storage_writer.py", "_patch_lock_unavailable"): frozenset(
        {
            "tests/unit/test_storage_writer.py::test_clear_in_band_account_swallows_lock_unavailable",
            "tests/unit/test_storage_writer.py::test_persist_minted_jar_fails_closed_on_lock_unavailable",
            "tests/unit/test_storage_writer.py::test_replace_from_login_failed_write_leaves_legacy_account_untouched",
            "tests/unit/test_storage_writer.py::test_replace_from_login_fails_closed_on_lock_unavailable",
            "tests/unit/test_storage_writer.py::test_replace_from_remint_takes_storage_lock",
            "tests/unit/test_storage_writer.py::test_update_account_metadata_fails_closed_on_lock_unavailable",
        }
    ),
    (
        "tests/unit/test_auth_master_token_bootstrap.py",
        "test_public_malformed_projection_preserves_ordinary_context.invoke",
    ): frozenset(
        {
            "tests/unit/test_auth_master_token_bootstrap.py::test_public_malformed_projection_preserves_ordinary_context[False]",
            "tests/unit/test_auth_master_token_bootstrap.py::test_public_malformed_projection_preserves_ordinary_context[True]",
        }
    ),
    (
        "tests/unit/test_refresh_lock_registry.py",
        "TestDoubleCancelDoesNotDetonateBridge.test_second_cancel_while_pending_preserves_bridge_and_siblings._run",
    ): frozenset(
        {
            "tests/unit/test_refresh_lock_registry.py::TestDoubleCancelDoesNotDetonateBridge::test_second_cancel_while_pending_preserves_bridge_and_siblings"
        }
    ),
    (
        "tests/unit/test_refresh_lock_registry.py",
        "TestPromptPopRetention.test_registry_does_not_accumulate_across_cycles._run",
    ): frozenset(
        {
            "tests/unit/test_refresh_lock_registry.py::TestPromptPopRetention::test_registry_does_not_accumulate_across_cycles"
        }
    ),
    (
        "tests/unit/test_auth_headless_reauth.py",
        "test_single_flight_is_unreachable_from_the_sync_drive_entry._drive_in_worker_thread._claim_from_worker",
    ): frozenset(
        {
            "tests/unit/test_auth_headless_reauth.py::test_single_flight_is_unreachable_from_the_sync_drive_entry"
        }
    ),
    (
        "tests/unit/test_refresh_lock_registry.py",
        "TestFlightClaimIdentity.test_distinct_keys_get_distinct_flights._run",
    ): frozenset(
        {
            "tests/unit/test_refresh_lock_registry.py::TestFlightClaimIdentity::test_distinct_keys_get_distinct_flights"
        }
    ),
    (
        "tests/unit/test_refresh_lock_registry.py",
        "TestFlightClaimIdentity.test_second_claim_same_key_follows_leader._run",
    ): frozenset(
        {
            "tests/unit/test_refresh_lock_registry.py::TestFlightClaimIdentity::test_second_claim_same_key_follows_leader"
        }
    ),
    (
        "tests/unit/test_refresh_lock_registry.py",
        "TestFlightClaimIdentity.test_settled_flight_is_overwritable_by_next_leader._run",
    ): frozenset(
        {
            "tests/unit/test_refresh_lock_registry.py::TestFlightClaimIdentity::test_settled_flight_is_overwritable_by_next_leader"
        }
    ),
    (
        "tests/unit/test_refresh_lock_registry.py",
        "TestClaimIfEpochCurrent.test_claims_when_epoch_unchanged._run",
    ): frozenset(
        {
            "tests/unit/test_refresh_lock_registry.py::TestClaimIfEpochCurrent::test_claims_when_epoch_unchanged"
        }
    ),
    (
        "tests/unit/test_refresh_lock_registry.py",
        "TestClaimIfEpochCurrent.test_skips_when_epoch_already_advanced._run",
    ): frozenset(
        {
            "tests/unit/test_refresh_lock_registry.py::TestClaimIfEpochCurrent::test_skips_when_epoch_already_advanced"
        }
    ),
    ("tests/unit/test_storage_writer.py", "_patch_master_token_lock_unavailable"): frozenset(
        {
            "tests/unit/test_storage_writer.py::test_write_master_token_fails_closed_on_lock_unavailable"
        }
    ),
    (
        "tests/unit/test_auth_account_promotion.py",
        "TestRetryableSingleFlight.test_concurrent_reads_of_one_profile_promote_exactly_once._read",
    ): frozenset(
        {
            "tests/unit/test_auth_account_promotion.py::TestRetryableSingleFlight::test_concurrent_reads_of_one_profile_promote_exactly_once"
        }
    ),
}


def _mutation_counter(rows: list[dict[str, Any]]) -> Counter[tuple[Any, ...]]:
    result: Counter[tuple[Any, ...]] = Counter()
    for row in rows:
        result[_mutation_identity(row)] += int(row["count"])
    return result


def _mutation_row_counter(rows: list[dict[str, Any]]) -> Counter[tuple[Any, ...]]:
    result: Counter[tuple[Any, ...]] = Counter()
    for row in rows:
        fields = MODULE_MUTATION_FIELDS if "module" in row else SHARED_MUTATION_FIELDS
        result[tuple(row[field] for field in sorted(fields))] += 1
    return result


def collect_mutation_projection(workspace: Path) -> list[dict[str, Any]]:
    """Run the head-version collectors against an arbitrary workspace."""
    if str(REPO_ROOT) not in sys.path:
        sys.path.insert(0, str(REPO_ROOT))
    from scripts.audit_auth_patch_sites import build_projection, collect_sites
    from scripts.audit_auth_shared_mutations import build_projection as build_shared
    from scripts.audit_auth_shared_mutations import collect_mutations

    tests = workspace / "tests"
    projections = [
        build_projection(collect_sites(tests, workspace / "src/notebooklm/_auth")),
        build_projection(
            collect_sites(
                tests,
                workspace / "src/notebooklm/_browser",
                package_dotted="notebooklm._browser",
            )
        ),
        build_projection(
            collect_sites(
                tests,
                workspace / "src/notebooklm/auth.py",
                package_dotted="notebooklm.auth",
            )
        ),
    ]
    module_rows = [
        dict(row)
        for projection in projections
        for row in cast(list[dict[str, Any]], projection.get("joint_sites", []))
    ]
    shared = build_shared(
        collect_mutations(
            tests,
            {
                "notebooklm._auth": workspace / "src/notebooklm/_auth",
                "notebooklm._browser": workspace / "src/notebooklm/_browser",
            },
        )
    )
    return [
        *module_rows,
        *(dict(row) for row in cast(list[dict[str, Any]], shared.get("mutations", []))),
    ]


def decreased_mutations(
    base_rows: list[dict[str, Any]], head_rows: list[dict[str, Any]]
) -> list[dict[str, Any]]:
    """Return each decreased full joint row with only the removed count."""
    base_by_id = {_mutation_identity(row): row for row in base_rows}
    old = _mutation_counter(base_rows)
    new = _mutation_counter(head_rows)
    result: list[dict[str, Any]] = []
    for identity, old_count in old.items():
        if old_count <= new[identity]:
            continue
        row = dict(base_by_id[identity])
        row["count"] = old_count - new[identity]
        result.append(row)
    return sorted(result, key=lambda row: tuple(str(item) for item in _mutation_identity(row)))


def _expected_consumers(
    mutations: list[dict[str, Any]], collection: dict[str, Any], label: str
) -> set[str]:
    expected: set[str] = set()
    items = collection.get("items", [])
    for mutation in mutations:
        path = mutation["path"]
        qualname = mutation["owner_qualname"]
        kind = mutation["owner_kind"]
        key = f"{path}::{qualname}"
        if kind == "test":
            canonical = f"{path}::{qualname.replace('.', '::')}"
            consumers = {
                item["nodeid"] for item in items if item.get("canonical_node") == canonical
            }
        elif kind == "fixture":
            consumers = set(collection.get("fixture_consumers", {}).get(key, []))
        else:
            if key in collection.get("unresolved_helpers", []):
                raise PolicyError(f"{label}: unresolved dynamic callers for {key}")
            consumers = set(collection.get("helper_consumers", {}).get(key, []))
        if not consumers:
            raise PolicyError(f"{label}: cannot resolve every {kind} consumer for {key}")
        expected.update(consumers)
    return expected


def validate_policy(
    policy: dict[str, Any],
    base: dict[str, Any],
    head: dict[str, Any],
    *,
    base_policy: dict[str, Any] | None = None,
    required_base_mutations: list[dict[str, Any]] | None = None,
    lifecycle_policy: dict[str, Any] | None = None,
    base_lifecycle_policy: dict[str, Any] | None = None,
) -> None:
    if policy.get("version") != 1 or not isinstance(policy.get("scenarios"), list):
        raise PolicyError("scenario policy must be version 1 with a scenarios list")
    if base_policy is not None and (
        base_policy.get("version") != 1 or not isinstance(base_policy.get("scenarios"), list)
    ):
        raise PolicyError("base scenario policy must be version 1 with a scenarios list")
    previous = {row["id"]: row for row in (base_policy or {}).get("scenarios", [])}
    ids: set[str] = set()
    replacement_users: set[str] = set()
    new_evidence: list[dict[str, Any]] = []
    for row in policy["scenarios"]:
        required = {
            "id",
            "base_selectors",
            "replacement_selectors",
            "node_mapping",
            "affected_paths",
            "contracts",
            "base_mutations",
        }
        if set(row) != required:
            raise PolicyError(f"scenario row has wrong fields: {set(row) ^ required}")
        if row["id"] in ids:
            raise PolicyError(f"duplicate scenario id: {row['id']}")
        ids.add(row["id"])
        is_new = row["id"] not in previous
        if not is_new and row != previous[row["id"]]:
            raise PolicyError(f"{row['id']}: existing scenario rows are immutable")
        if (
            not isinstance(row["affected_paths"], list)
            or not row["affected_paths"]
            or not all(_is_normalized_affected_path(path) for path in row["affected_paths"])
            or len(row["affected_paths"]) != len(set(row["affected_paths"]))
        ):
            raise PolicyError(
                f"{row['id']}: affected_paths must name exact normalized production files"
            )
        if not row["contracts"] or not set(row["contracts"]) <= CONTRACT_TAGS:
            raise PolicyError(f"{row['id']}: unknown or empty contract tags")
        mutations = [
            _validate_mutation(mutation, f"{row['id']} base_mutations")
            for mutation in row["base_mutations"]
        ]
        if not mutations:
            raise PolicyError(f"{row['id']}: base_mutations cannot be empty")
        old_nodes = _expand(row["base_selectors"], base, f"{row['id']} base") if is_new else set()
        new_nodes = _expand(row["replacement_selectors"], head, f"{row['id']} head")
        non_passing = {
            item["nodeid"]: item.get("non_passing_markers", [])
            for item in head.get("items", [])
            if item["nodeid"] in new_nodes and item.get("non_passing_markers")
        }
        if non_passing:
            raise PolicyError(
                f"{row['id']}: replacement nodes are not passing CI evidence: {non_passing}"
            )
        if not row["node_mapping"] or any(
            not isinstance(entry, dict)
            or set(entry) != {"base", "head"}
            or not isinstance(entry["head"], list)
            or not entry["head"]
            for entry in row["node_mapping"]
        ):
            raise PolicyError(f"{row['id']}: node mapping has invalid rows")
        mapping_domain = [entry["base"] for entry in row["node_mapping"]]
        mapping_codomain = [node for entry in row["node_mapping"] for node in entry["head"]]
        if len(mapping_domain) != len(set(mapping_domain)) or len(mapping_codomain) != len(
            set(mapping_codomain)
        ):
            raise PolicyError(f"{row['id']}: node mapping contains duplicate nodes")
        if (is_new and set(mapping_domain) != old_nodes) or set(mapping_codomain) != new_nodes:
            raise PolicyError(f"{row['id']}: node mapping is not exact")
        if replacement_users & new_nodes:
            raise PolicyError(
                f"{row['id']}: replacement node reused; encode a split/merge as one group row"
            )
        replacement_users.update(new_nodes)
        if is_new:
            unresolved_keys = set(base.get("unresolved_helpers", []))
            unresolved = [
                mutation
                for mutation in mutations
                if mutation["owner_kind"] == "helper"
                and f"{mutation['path']}::{mutation['owner_qualname']}" in unresolved_keys
            ]
            unexpected = [
                mutation
                for mutation in unresolved
                if _unresolved_helper_mutation_key(mutation)
                not in _PINNED_UNRESOLVED_HELPER_MUTATIONS
            ]
            if unexpected:
                mutation = unexpected[0]
                key = f"{mutation['path']}::{mutation['owner_qualname']}"
                raise PolicyError(f"{row['id']}: unresolved dynamic callers for {key}")
            resolvable = [mutation for mutation in mutations if mutation not in unresolved]
            expected = _expected_consumers(resolvable, base, row["id"])
            for mutation in unresolved:
                expected.update(
                    _PINNED_UNRESOLVED_HELPER_CONSUMERS[
                        (mutation["path"], mutation["owner_qualname"])
                    ]
                )
            if old_nodes != expected:
                raise PolicyError(
                    f"{row['id']}: selectors do not exactly cover helper/fixture consumers"
                )
        if is_new:
            new_evidence.extend(mutations)
    removed_ids = set(previous) - ids
    if removed_ids:
        raise PolicyError(f"scenario rows cannot be deleted: {sorted(removed_ids)}")
    if required_base_mutations is not None:

        def normalize_lifecycle_row(row: dict[str, Any]) -> str:
            normalized = dict(row)
            legacy = normalized.pop("replaced_base_mutation", None)
            if "replaced_base_mutations" not in normalized:
                normalized["replaced_base_mutations"] = [] if legacy is None else [legacy]
            return json.dumps(normalized, sort_keys=True)

        old_lifecycle_rows = {
            normalize_lifecycle_row(row)
            for row in (base_lifecycle_policy or {}).get("operations", [])
        }
        lifecycle_evidence = [
            _validate_mutation(mutation, "lifecycle replacement")
            for row in (lifecycle_policy or {}).get("operations", [])
            if normalize_lifecycle_row(row) not in old_lifecycle_rows
            for mutation in row.get("replaced_base_mutations", [])
        ]
        if _mutation_row_counter([*new_evidence, *lifecycle_evidence]) != _mutation_row_counter(
            required_base_mutations
        ):
            raise PolicyError(
                "new scenario/lifecycle evidence does not exactly match decreased joint rows"
            )


def _policy_at_revision(revision: str, path: Path) -> dict[str, Any]:
    rel = path.resolve().relative_to(REPO_ROOT).as_posix()
    result = subprocess.run(
        ["git", "show", f"{revision}:{rel}"],
        cwd=REPO_ROOT,
        text=True,
        capture_output=True,
    )
    if result.returncode != 0:
        return {"version": 1, "scenarios": []}
    return json.loads(result.stdout)


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    sub = parser.add_subparsers(dest="command", required=True)
    collect = sub.add_parser("collect")
    collect.add_argument("--workspace", type=Path, required=True)
    collect.add_argument("--output", type=Path, required=True)
    validate = sub.add_parser("validate")
    validate.add_argument("--base-collection", type=Path, required=True)
    validate.add_argument("--head-collection", type=Path, required=True)
    validate.add_argument("--base-revision", required=True)
    validate.add_argument("--policy", type=Path, default=DEFAULT_POLICY)
    validate_head = sub.add_parser("validate-head")
    validate_head.add_argument("--policy", type=Path, default=DEFAULT_POLICY)
    args = parser.parse_args(argv)
    try:
        if args.command == "collect":
            args.output.write_text(
                json.dumps(collect_workspace(args.workspace), indent=2, sort_keys=True) + "\n",
                encoding="utf-8",
            )
        elif args.command == "validate-head":
            head = collect_workspace(REPO_ROOT)
            policy = load_json(args.policy)
            validate_policy(policy, head, head, base_policy=policy)
        else:
            base = load_json(args.base_collection)
            head = load_json(args.head_collection)
            policy = load_json(args.policy)
            base_policy = _policy_at_revision(args.base_revision, args.policy)
            base_lifecycle = _policy_at_revision(args.base_revision, LIFECYCLE_POLICY)
            lifecycle = load_json(LIFECYCLE_POLICY)
            try:
                base_workspace = Path(base["workspace"])
                head_workspace = Path(head["workspace"])
            except (KeyError, TypeError) as exc:
                raise PolicyError("collection artifacts must record their workspace") from exc
            required = decreased_mutations(
                collect_mutation_projection(base_workspace),
                collect_mutation_projection(head_workspace),
            )
            validate_policy(
                policy,
                base,
                head,
                base_policy=base_policy,
                required_base_mutations=required,
                lifecycle_policy=lifecycle,
                base_lifecycle_policy=base_lifecycle,
            )
    except PolicyError as exc:
        parser.error(str(exc))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall