"""Virtual core resource type definitions for the Resource Registry.

Contains the built-in virtual type entries (file, directory, commit,
branch, tag, tree) that are appended to ``BUILTIN_TYPES`` in
``_resource_registry_data``.  Extracted to keep each module under the
500-line CONTRIBUTING limit.

.. note::

    This is an **internal** module (``_``-prefixed).  External code
    should import ``BUILTIN_TYPES`` from ``_resource_registry_data``
    instead.
"""

from __future__ import annotations

from typing import Any

__all__ = ["VIRTUAL_CORE_TYPES"]

# === Virtual Core Resource Types (#329) ===
#
# Virtual types represent abstract identities that link equivalent
# physical resources across layers and repositories.  They have no
# handler, no sandbox strategy, and are never user-addable.
#
# NOTE: Some ``child_types`` entries (e.g. ``git-tree-entry``,
# ``git-tree``, ``git-commit``, ``git-branch``, ``git-tag``) are
# forward references to deferred physical types introduced by PR #662
# (issue #330).  This is safe because the registry stores child_types
# as opaque strings with no referential-integrity check at bootstrap
# time -- see ``bootstrap_builtin_types()`` and ``spec_to_db()``.

VIRTUAL_CORE_TYPES: list[dict[str, Any]] = [
    {
        "name": "file",
        "description": (
            "Cross-layer file identity linking equivalent physical files "
            "by content hash, filename, and permissions."
        ),
        "resource_kind": "virtual",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": [],
        "child_types": ["fs-file", "git-tree-entry"],
        "handler": None,
        "capabilities": {
            "read": False,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
        "equivalence": {
            "criteria": ["content_hash", "filename", "permissions"],
            "description": (
                "Two physical resources are equivalent when they share "
                "the same content bytes (SHA-256), filename, and permissions"
            ),
        },
    },
    {
        "name": "directory",
        "description": (
            "Cross-layer directory identity linking equivalent physical "
            "directories by recursive content."
        ),
        "resource_kind": "virtual",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": [],
        "child_types": ["fs-directory", "git-tree"],
        "handler": None,
        "capabilities": {
            "read": False,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
        # Spec identity table lists only merkle_hash, but name and permissions
        # are added for stricter matching (same recursive content in a
        # differently-named or differently-permissioned directory is not
        # considered equivalent).  See specification.md ~line 24623.
        "equivalence": {
            "criteria": ["merkle_hash", "name", "permissions"],
            "description": (
                "Two physical resources are equivalent when their "
                "recursive contents produce the same Merkle hash"
            ),
        },
    },
    {
        "name": "commit",
        "description": (
            "Cross-repo commit identity linking commits with "
            "the same hash across repositories."
        ),
        "resource_kind": "virtual",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": [],
        "child_types": ["git-commit"],
        "handler": None,
        "capabilities": {
            "read": False,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
        "equivalence": {
            "criteria": ["commit_hash"],
            "description": (
                "Two physical commits are equivalent when they "
                "share the same commit hash"
            ),
        },
    },
    {
        "name": "branch",
        "description": (
            "Cross-repo branch identity linking branches with "
            "the same name and HEAD commit hash."
        ),
        "resource_kind": "virtual",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": [],
        "child_types": ["git-branch"],
        "handler": None,
        "capabilities": {
            "read": False,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
        "equivalence": {
            "criteria": ["name", "head_commit_hash"],
            "description": (
                "Two physical branches are equivalent when they share "
                "the same branch name and HEAD commit hash"
            ),
        },
    },
    {
        "name": "tag",
        "description": (
            "Cross-repo tag identity linking tags with the same name and target object."
        ),
        "resource_kind": "virtual",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": [],
        "child_types": ["git-tag"],
        "handler": None,
        "capabilities": {
            "read": False,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
        "equivalence": {
            "criteria": ["name", "target_sha"],
            "description": (
                "Two physical tags are equivalent when they share "
                "the same tag name and target object"
            ),
        },
    },
    {
        "name": "tree",
        "description": (
            "Cross-repo/cross-commit tree identity linking trees with the same hash."
        ),
        "resource_kind": "virtual",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": [],
        "child_types": ["git-tree"],
        "handler": None,
        "capabilities": {
            "read": False,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
        "equivalence": {
            "criteria": ["tree_hash"],
            "description": (
                "Two physical tree objects are equivalent when they "
                "share the same tree hash"
            ),
        },
    },
]
