"""Future feature markers — skipped tests that document expected behavior.

These tests are intentionally skipped because they depend on backend APIs
that don't exist yet. They serve as living documentation and a readiness
checklist: when a backend feature lands, remove the skip marker, implement
the feature, and make the test pass.

Run with `pytest -rs` to see skip reasons in the output.
"""

from __future__ import annotations

import pytest


# ─── §32 Structured Tagging ────────────────────────────────────────────────

@pytest.mark.skip(reason="Blocked on backend §32: PUT /attestation/{id}/tags not implemented")
class TestStructuredTagging:
    """Census should support --tag key=value on scan for multi-dimensional classification."""

    def test_scan_with_tags(self):
        """census scan /path --tag department=hr --tag level=confidential"""

    def test_manifest_stores_tags(self):
        """ManifestEntry should carry tags dict alongside hash, path, size, mtime."""

    def test_tag_query_local(self):
        """census status --filter department=hr should filter manifest entries by tag."""

    def test_tag_roundtrip_save_load(self):
        """Tags should survive manifest JSON save/load cycle."""

    def test_tag_encrypted_value(self):
        """--tag-encrypted level=secret should use SDK client-side encryption."""


# ─── §33 Derived Lists ─────────────────────────────────────────────────────

@pytest.mark.skip(reason="Blocked on backend §33: POST /census/list not implemented")
class TestDerivedLists:
    """Census should produce HMAC-derived lists for selective third-party cooperation."""

    def test_list_create_from_manifest(self):
        """census list create --manifest m.json --label forensic-2026Q1"""

    def test_list_create_with_tag_filter(self):
        """census list create --manifest m.json --filter department=hr"""

    def test_list_verify_match(self):
        """census list verify --list-id <uuid> --list-key <hex> /suspect/dir"""

    def test_list_verify_no_match(self):
        """Suspect files not in derived list should report zero matches."""

    def test_derived_hash_is_hmac_sha256(self):
        """derived_H = HMAC-SHA256(H, list_key) — verify against known test vector."""

    def test_list_key_not_stored_locally(self):
        """list_key should only appear in the creation response, never in manifest."""

    def test_list_expiry_and_revocation(self):
        """Expired or revoked lists should fail verification gracefully."""


# ─── §10 Bulk Endpoints ────────────────────────────────────────────────────

@pytest.mark.skip(reason="Blocked on backend §10: POST /attest/bulk not implemented")
class TestBulkScale:
    """Census should support bulk attestation/verification (10K+ hashes per call)."""

    def test_scan_uses_bulk_when_available(self):
        """scan should prefer bulk endpoint when SDK exposes it."""

    def test_compare_uses_bulk_verify(self):
        """compare should prefer bulk verify for >100 hashes."""

    def test_bulk_fallback_to_batch(self):
        """If bulk endpoint fails, fall back to 100-hash batch chunking."""


# ─── §30 Forensic Sharing ──────────────────────────────────────────────────

@pytest.mark.skip(reason="Blocked on backend §30: Forensic sharing tokens not implemented")
class TestForensicSharing:
    """Census should support sharing attestation evidence with third parties."""

    def test_share_creates_token(self):
        """census share --attestation att_123 --expires 7d"""

    def test_share_token_scoped_readonly(self):
        """Share tokens should provide read-only access to evidence only."""
