specfact-cli 0.31.0__tar.gz → 0.32.0__tar.gz

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/.gitignore

@@ -138,4 +138,6 @@ harness_contracts.py
 # semgrep artifacts
 lang.json
 Language.ml
-Language.mli
+Language.mli
+
+.artifacts

specfact_cli-0.31.0/LICENSE.md → specfact_cli-0.32.0/LICENSE

@@ -35,8 +35,7 @@
       "Work" shall mean the work of authorship, whether in Source or
       Object form, made available under the License, as indicated by a
       copyright notice that is included in or attached to the work
-      (which shall not include Communications that are clearly marked or
-      otherwise designated in writing by the copyright owner as "Not a Work").
+      (an example is provided in the Appendix below).
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
@@ -57,8 +56,8 @@
       communication on electronic mailing lists, source code control systems,
       and issue tracking systems that are managed by, or on behalf of, the
       Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is clearly marked or otherwise designated
-      in writing by the copyright owner as "Not a Contribution".
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
 
       "Contributor" shall mean Licensor and any individual or Legal Entity
       on behalf of whom a Contribution has been received by Licensor and

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.31.0
+Version: 0.32.0
 Summary: The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git
@@ -45,8 +45,7 @@ License:                                  Apache License
               "Work" shall mean the work of authorship, whether in Source or
               Object form, made available under the License, as indicated by a
               copyright notice that is included in or attached to the work
-              (which shall not include Communications that are clearly marked or
-              otherwise designated in writing by the copyright owner as "Not a Work").
+              (an example is provided in the Appendix below).
         
               "Derivative Works" shall mean any work, whether in Source or Object
               form, that is based on (or derived from) the Work and for which the
@@ -67,8 +66,8 @@ License:                                  Apache License
               communication on electronic mailing lists, source code control systems,
               and issue tracking systems that are managed by, or on behalf of, the
               Licensor for the purpose of discussing and improving the Work, but
-              excluding communication that is clearly marked or otherwise designated
-              in writing by the copyright owner as "Not a Contribution".
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
         
               "Contributor" shall mean Licensor and any individual or Legal Entity
               on behalf of whom a Contribution has been received by Licensor and
@@ -210,7 +209,7 @@ License:                                  Apache License
            WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
            See the License for the specific language governing permissions and
            limitations under the License.
-License-File: LICENSE.md
+License-File: LICENSE
 Keywords: agile,backlog,beartype,ceremonies,cli,contract-driven-development,contracts,crosshair,devops,existing-code,icontract,kanban,legacy,modernization,policy-as-code,property-based-testing,safe,scrum,specfact,specs,tdd,validation
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -286,7 +285,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg?color=22c55e)](https://pypi.org/project/specfact-cli/)
 [![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE.md)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Status](https://img.shields.io/badge/status-beta-F59E0B.svg)](https://github.com/nold-ai/specfact-cli)
 
 <div align="center">
@@ -442,6 +441,7 @@ Contract-first module architecture highlights:
 - Registration tracks protocol operation coverage and schema compatibility metadata.
 - Bridge registry support allows module manifests to declare `service_bridges` converters (for example ADO/Jira/Linear/GitHub) loaded at lifecycle startup without direct core-to-module imports.
 - Protocol reporting classifies modules from effective runtime interfaces with a single aggregate summary (`Full/Partial/Legacy`).
+- Module manifests support publisher and integrity metadata (arch-06) with optional checksum and signature verification at registration time.
 
 Why this matters:
 
@@ -521,7 +521,7 @@ hatch run contract-test-full
 
 **Apache License 2.0** - Open source and enterprise-friendly.
 
-[Full license](LICENSE.md)
+[Full license](LICENSE)
 
 ---
 

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/README.md

@@ -8,7 +8,7 @@
 
 [![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg?color=22c55e)](https://pypi.org/project/specfact-cli/)
 [![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE.md)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Status](https://img.shields.io/badge/status-beta-F59E0B.svg)](https://github.com/nold-ai/specfact-cli)
 
 <div align="center">
@@ -164,6 +164,7 @@ Contract-first module architecture highlights:
 - Registration tracks protocol operation coverage and schema compatibility metadata.
 - Bridge registry support allows module manifests to declare `service_bridges` converters (for example ADO/Jira/Linear/GitHub) loaded at lifecycle startup without direct core-to-module imports.
 - Protocol reporting classifies modules from effective runtime interfaces with a single aggregate summary (`Full/Partial/Legacy`).
+- Module manifests support publisher and integrity metadata (arch-06) with optional checksum and signature verification at registration time.
 
 Why this matters:
 
@@ -243,7 +244,7 @@ hatch run contract-test-full
 
 **Apache License 2.0** - Open source and enterprise-friendly.
 
-[Full license](LICENSE.md)
+[Full license](LICENSE)
 
 ---
 

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.31.0"
+version = "0.32.0"
 description = "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases."
 readme = "README.md"
 requires-python = ">=3.11"
-license = { file = "LICENSE.md" }  # Apache License 2.0
+license = { file = "LICENSE" }  # Apache License 2.0
 authors = [
     {name = "NOLD AI (Owner: Dominikus Nold)", email = "hello@noldai.com"}
 ]
@@ -385,7 +385,7 @@ include = [
     "/src",
     "/resources",
     "/README.md",
-    "/LICENSE.md",
+    "/LICENSE",
     "/pyproject.toml",
 ]
 # Exclude development files, tests, docs, tools, etc.

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.31.0"
+__version__ = "0.32.0"

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/src/specfact_cli/__init__.py

@@ -8,6 +8,6 @@ This package provides command-line tools for:
 - Supporting agile ceremonies and team workflows
 """
 
-__version__ = "0.31.0"
+__version__ = "0.32.0"
 
 __all__ = ["__version__"]

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/src/specfact_cli/analyzers/code_analyzer.py

@@ -126,11 +126,13 @@ class CodeAnalyzer:
     @beartype
     @ensure(lambda result: isinstance(result, PlanBundle), "Must return PlanBundle")
     @ensure(
-        lambda result: isinstance(result, PlanBundle)
-        and hasattr(result, "version")
-        and hasattr(result, "features")
-        and result.version == get_current_schema_version()  # type: ignore[reportUnknownMemberType]
-        and len(result.features) >= 0,  # type: ignore[reportUnknownMemberType]
+        lambda result: (
+            isinstance(result, PlanBundle)
+            and hasattr(result, "version")
+            and hasattr(result, "features")
+            and result.version == get_current_schema_version()  # type: ignore[reportUnknownMemberType]
+            and len(result.features) >= 0
+        ),  # type: ignore[reportUnknownMemberType]
         "Plan bundle must be valid",
     )
     def analyze(self) -> PlanBundle:

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/src/specfact_cli/models/change.py

@@ -48,13 +48,17 @@ class FeatureDelta(BaseModel):
 
     @model_validator(mode="after")
     @require(
-        lambda self: self.change_type == ChangeType.ADDED
-        or (self.change_type in (ChangeType.MODIFIED, ChangeType.REMOVED) and self.original_feature is not None),
+        lambda self: (
+            self.change_type == ChangeType.ADDED
+            or (self.change_type in (ChangeType.MODIFIED, ChangeType.REMOVED) and self.original_feature is not None)
+        ),
         "MODIFIED/REMOVED changes must have original_feature",
     )
     @require(
-        lambda self: self.change_type == ChangeType.REMOVED
-        or (self.change_type in (ChangeType.ADDED, ChangeType.MODIFIED) and self.proposed_feature is not None),
+        lambda self: (
+            self.change_type == ChangeType.REMOVED
+            or (self.change_type in (ChangeType.ADDED, ChangeType.MODIFIED) and self.proposed_feature is not None)
+        ),
         "ADDED/MODIFIED changes must have proposed_feature",
     )
     @ensure(lambda result: isinstance(result, FeatureDelta), "Must return FeatureDelta")

specfact_cli-0.32.0/src/specfact_cli/models/module_package.py

@@ -0,0 +1,158 @@
+"""Module package metadata models."""
+
+from __future__ import annotations
+
+import re
+
+from beartype import beartype
+from icontract import ensure
+from pydantic import BaseModel, Field, model_validator
+
+
+CHECKSUM_ALGO_RE = re.compile(r"^sha256:[a-fA-F0-9]{64}$|^sha384:[a-fA-F0-9]{96}$|^sha512:[a-fA-F0-9]{128}$")
+CONVERTER_CLASS_PATH_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)+$")
+MODULE_NAME_RE = re.compile(r"^[a-z][a-z0-9_-]*$")
+FIELD_NAME_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
+@beartype
+class SchemaExtension(BaseModel):
+    """Declarative schema extension for Feature or ProjectBundle (arch-07)."""
+
+    target: str = Field(..., description="Target model: Feature or ProjectBundle")
+    field: str = Field(..., description="Field name (snake_case)")
+    type_hint: str = Field(..., description="Type hint for documentation (e.g. str, int)")
+    description: str = Field(default="", description="Human-readable description")
+
+    @model_validator(mode="after")
+    def _validate_target_and_field(self) -> SchemaExtension:
+        if self.target not in ("Feature", "ProjectBundle"):
+            raise ValueError("target must be Feature or ProjectBundle")
+        if not FIELD_NAME_RE.match(self.field):
+            raise ValueError("field must match [a-z][a-z0-9_]*")
+        return self
+
+
+@beartype
+class PublisherInfo(BaseModel):
+    """Publisher identity from module manifest (arch-06)."""
+
+    name: str = Field(..., description="Publisher display name")
+    email: str = Field(..., description="Publisher contact email")
+    attributes: dict[str, str] = Field(default_factory=dict, description="Optional publisher attributes")
+
+    @model_validator(mode="after")
+    def _validate_non_empty(self) -> PublisherInfo:
+        if not self.name.strip():
+            raise ValueError("Publisher name must not be empty")
+        if not self.email.strip():
+            raise ValueError("Publisher email must not be empty")
+        return self
+
+
+@beartype
+class IntegrityInfo(BaseModel):
+    """Integrity metadata for module artifact verification (arch-06)."""
+
+    checksum: str = Field(..., description="Checksum in algo:hex format (e.g. sha256:...)")
+    signature: str | None = Field(default=None, description="Optional detached signature (base64)")
+
+    @model_validator(mode="after")
+    def _validate_checksum_format(self) -> IntegrityInfo:
+        """Validation SHALL ensure checksum format correctness."""
+        if not CHECKSUM_ALGO_RE.match(self.checksum):
+            raise ValueError(
+                "integrity.checksum must be algo:hex (e.g. sha256:<64 hex chars>, sha384:<96>, sha512:<128>)"
+            )
+        return self
+
+
+@beartype
+class ServiceBridgeMetadata(BaseModel):
+    """Service bridge declaration from module package manifest."""
+
+    id: str = Field(..., description="Bridge identifier (for example: ado, jira, linear, github).")
+    converter_class: str = Field(..., description="Fully-qualified converter class path.")
+    description: str | None = Field(default=None, description="Optional bridge description.")
+
+    @model_validator(mode="after")
+    def _validate_bridge_metadata(self) -> ServiceBridgeMetadata:
+        """Validate required bridge fields."""
+        if not self.id.strip():
+            raise ValueError("service_bridges.id must not be empty.")
+        if not self.converter_class.strip():
+            raise ValueError("service_bridges.converter_class must not be empty.")
+        if not CONVERTER_CLASS_PATH_RE.match(self.converter_class):
+            raise ValueError(
+                "service_bridges.converter_class must be a dotted path (for example: package.module.ClassName)."
+            )
+        return self
+
+
+@beartype
+class VersionedModuleDependency(BaseModel):
+    """Versioned module dependency entry (arch-06)."""
+
+    name: str = Field(..., description="Module package id")
+    version_specifier: str | None = Field(default=None, description="PEP 440 version specifier")
+
+
+@beartype
+class VersionedPipDependency(BaseModel):
+    """Versioned pip dependency entry (arch-06)."""
+
+    name: str = Field(..., description="PyPI package name")
+    version_specifier: str | None = Field(default=None, description="PEP 440 version specifier")
+
+
+@beartype
+class ModulePackageMetadata(BaseModel):
+    """Schema for a module package manifest."""
+
+    name: str = Field(..., description="Package identifier (e.g. backlog_refine)")
+    version: str = Field(default="0.1.0", description="Package version")
+    commands: list[str] = Field(default_factory=list, description="Command names this package provides")
+    command_help: dict[str, str] | None = Field(
+        default=None,
+        description="Optional command name -> help text for root help.",
+    )
+    pip_dependencies: list[str] = Field(default_factory=list, description="Optional pip dependencies")
+    module_dependencies: list[str] = Field(default_factory=list, description="Optional other package ids")
+    core_compatibility: str | None = Field(
+        default=None,
+        description="CLI core version compatibility (PEP 440 specifier, e.g. '>=0.28.0,<1.0.0').",
+    )
+    tier: str = Field(default="community", description="Tier: community or enterprise")
+    addon_id: str | None = Field(default=None, description="Optional addon identifier")
+    schema_version: str | None = Field(
+        default=None,
+        description="Compatible ProjectBundle schema version. None means current schema.",
+    )
+    protocol_operations: list[str] = Field(
+        default_factory=list,
+        description="Detected ModuleIOContract operations: import, export, sync, validate.",
+    )
+    publisher: PublisherInfo | None = Field(default=None, description="Publisher identity (arch-06)")
+    integrity: IntegrityInfo | None = Field(default=None, description="Integrity metadata (arch-06)")
+    module_dependencies_versioned: list[VersionedModuleDependency] = Field(
+        default_factory=list,
+        description="Versioned module dependency declarations (arch-06)",
+    )
+    pip_dependencies_versioned: list[VersionedPipDependency] = Field(
+        default_factory=list,
+        description="Versioned pip dependency declarations (arch-06)",
+    )
+    service_bridges: list[ServiceBridgeMetadata] = Field(
+        default_factory=list,
+        description="Optional bridge declarations for converter registration.",
+    )
+    schema_extensions: list[SchemaExtension] = Field(
+        default_factory=list,
+        description="Declarative schema extensions for Feature/ProjectBundle (arch-07).",
+    )
+
+    @beartype
+    @ensure(lambda result: isinstance(result, list), "Validated bridges must be returned as a list")
+    def validate_service_bridges(self) -> list[ServiceBridgeMetadata]:
+        """Return validated bridge declarations for lifecycle registration."""
+        return list(self.service_bridges)

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/src/specfact_cli/models/plan.py

@@ -7,13 +7,20 @@ and stories following the CLI-First specification.
 
 from __future__ import annotations
 
+import re
 from typing import Any
 
+from beartype import beartype
+from icontract import ensure, require
 from pydantic import BaseModel, Field, model_validator
 
 from specfact_cli.models.source_tracking import SourceTracking
 
 
+MODULE_NAME_RE = re.compile(r"^[a-z][a-z0-9_-]*$")
+FIELD_NAME_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
 class Story(BaseModel):
     """User story model following Scrum/Agile practices."""
 
@@ -121,6 +128,29 @@ class Feature(BaseModel):
     estimated_story_points: int | None = Field(
         default=None, description="Total estimated story points (sum of all stories, computed automatically)"
     )
+    extensions: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Module-scoped extension data (namespace-prefixed keys, e.g. backlog.ado_work_item_id)",
+    )
+
+    @beartype
+    @require(lambda module_name: bool(MODULE_NAME_RE.match(module_name)), "Invalid module name format")
+    @require(lambda field: bool(FIELD_NAME_RE.match(field)), "Invalid field name format")
+    def get_extension(self, module_name: str, field: str, default: Any = None) -> Any:
+        """Return extension value at module.field or default."""
+        if "." in module_name:
+            raise ValueError("Invalid module name format")
+        return self.extensions.get(f"{module_name}.{field}", default)
+
+    @beartype
+    @require(lambda module_name: bool(MODULE_NAME_RE.match(module_name)), "Invalid module name format")
+    @require(lambda field: bool(FIELD_NAME_RE.match(field)), "Invalid field name format")
+    @ensure(lambda self, module_name, field: f"{module_name}.{field}" in self.extensions)
+    def set_extension(self, module_name: str, field: str, value: Any) -> None:
+        """Store extension value at module.field."""
+        if "." in module_name:
+            raise ValueError("Invalid module name format")
+        self.extensions[f"{module_name}.{field}"] = value
 
 
 class Release(BaseModel):

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/src/specfact_cli/models/project.py

@@ -10,6 +10,7 @@ support dual versioning (schema + project).
 from __future__ import annotations
 
 import os
+import re
 from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import UTC, datetime
@@ -33,6 +34,10 @@ from specfact_cli.models.plan import (
 )
 
 
+_EXT_MODULE_RE = re.compile(r"^[a-z][a-z0-9_-]*$")
+_EXT_FIELD_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
 class BundleFormat(StrEnum):
     """Bundle format types."""
 
@@ -217,6 +222,29 @@ class ProjectBundle(BaseModel):
         default=None,
         description="Change tracking (tool-agnostic capability, used by OpenSpec and potentially others) (v1.1+)",
     )
+    extensions: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Module-scoped extension data (namespace-prefixed keys, e.g. sync.last_sync_timestamp)",
+    )
+
+    @beartype
+    @require(lambda self, module_name: bool(_EXT_MODULE_RE.match(module_name)), "Invalid module name format")
+    @require(lambda self, field: bool(_EXT_FIELD_RE.match(field)), "Invalid field name format")
+    def get_extension(self, module_name: str, field: str, default: Any = None) -> Any:
+        """Return extension value at module.field or default."""
+        if "." in module_name:
+            raise ValueError("Invalid module name format")
+        return self.extensions.get(f"{module_name}.{field}", default)
+
+    @beartype
+    @require(lambda self, module_name: bool(_EXT_MODULE_RE.match(module_name)), "Invalid module name format")
+    @require(lambda self, field: bool(_EXT_FIELD_RE.match(field)), "Invalid field name format")
+    @ensure(lambda self, module_name, field: f"{module_name}.{field}" in self.extensions)
+    def set_extension(self, module_name: str, field: str, value: Any) -> None:
+        """Store extension value at module.field."""
+        if "." in module_name:
+            raise ValueError("Invalid module name format")
+        self.extensions[f"{module_name}.{field}"] = value
 
     @model_validator(mode="before")
     @classmethod

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/src/specfact_cli/modules/backlog/src/commands.py

@@ -3626,10 +3626,9 @@ def refine(
 
 @app.command("map-fields")
 @require(
-    lambda ado_org, ado_project: isinstance(ado_org, str)
-    and len(ado_org) > 0
-    and isinstance(ado_project, str)
-    and len(ado_project) > 0,
+    lambda ado_org, ado_project: (
+        isinstance(ado_org, str) and len(ado_org) > 0 and isinstance(ado_project, str) and len(ado_project) > 0
+    ),
     "ADO org and project must be non-empty strings",
 )
 @beartype

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/src/specfact_cli/modules/plan/src/commands.py

@@ -3025,9 +3025,9 @@ def _load_and_validate_plan(plan: Path) -> tuple[bool, PlanBundle | None]:
 
 @beartype
 @require(
-    lambda bundle, bundle_dir, auto_enrich: isinstance(bundle, PlanBundle)
-    and bundle_dir is not None
-    and isinstance(bundle_dir, Path),
+    lambda bundle, bundle_dir, auto_enrich: (
+        isinstance(bundle, PlanBundle) and bundle_dir is not None and isinstance(bundle_dir, Path)
+    ),
     "Bundle must be PlanBundle and bundle_dir must be non-None Path",
 )
 @ensure(lambda result: result is None, "Must return None")

{specfact_cli-0.31.0 → specfact_cli-0.32.0}/src/specfact_cli/modules/sync/src/commands.py

@@ -1084,8 +1084,9 @@ def _sync_tool_to_specfact(
 )
 @require(lambda bidirectional: isinstance(bidirectional, bool), "Bidirectional must be bool")
 @require(
-    lambda mode: mode is None
-    or mode in ("read-only", "export-only", "import-annotation", "bidirectional", "unidirectional"),
+    lambda mode: (
+        mode is None or mode in ("read-only", "export-only", "import-annotation", "bidirectional", "unidirectional")
+    ),
     "Mode must be valid sync mode",
 )
 @require(lambda overwrite: isinstance(overwrite, bool), "Overwrite must be bool")

specfact_cli-0.32.0/src/specfact_cli/registry/crypto_validator.py

@@ -0,0 +1,124 @@
+"""
+Checksum and optional signature verification for module artifacts (arch-06).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+from pathlib import Path
+
+from beartype import beartype
+from icontract import require
+
+
+_ArtifactInput = bytes | Path
+
+
+def _algo_and_hex(expected_checksum: str) -> tuple[str, str]:
+    """Parse 'algo:hex' format. Raises ValueError if invalid."""
+    if ":" not in expected_checksum or not expected_checksum.strip():
+        raise ValueError("Expected checksum must be in algo:hex format (e.g. sha256:<64 hex chars>)")
+    algo, hex_part = expected_checksum.strip().split(":", 1)
+    algo = algo.lower()
+    if algo not in ("sha256", "sha384", "sha512"):
+        raise ValueError("Supported checksum algorithms: sha256, sha384, sha512")
+    if not hex_part or not all(c in "0123456789abcdefABCDEF" for c in hex_part):
+        raise ValueError("Checksum hex part must contain only hex digits")
+    expected_len = {"sha256": 64, "sha384": 96, "sha512": 128}
+    if len(hex_part) != expected_len[algo]:
+        raise ValueError(f"Checksum hex length for {algo} must be {expected_len[algo]}, got {len(hex_part)}")
+    return algo, hex_part
+
+
+@beartype
+@require(lambda expected_checksum: expected_checksum.strip() != "", "Expected checksum must not be empty")
+def verify_checksum(artifact: _ArtifactInput, expected_checksum: str) -> bool:
+    """
+    Verify artifact checksum against expected algo:hex value.
+
+    Args:
+        artifact: Raw bytes or path to file.
+        expected_checksum: Expected value in format sha256:<64 hex>, sha384:<96>, or sha512:<128>.
+
+    Returns:
+        True if the artifact's checksum matches.
+
+    Raises:
+        ValueError: If format is invalid or checksum does not match.
+    """
+    algo, expected_hex = _algo_and_hex(expected_checksum)
+    data = artifact.read_bytes() if isinstance(artifact, Path) else artifact
+    hasher = hashlib.new(algo)
+    hasher.update(data)
+    actual_hex = hasher.hexdigest()
+    if actual_hex.lower() != expected_hex.lower():
+        raise ValueError(f"Checksum mismatch: computed {algo}:{actual_hex[:16]}... does not match expected")
+    return True
+
+
+def _verify_signature_impl(artifact: bytes, signature_b64: str, public_key_pem: str) -> bool:
+    """
+    Verify detached signature over artifact using public key.
+    Uses cryptography if available; otherwise raises.
+    """
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives import hashes, serialization
+        from cryptography.hazmat.primitives.asymmetric import ed25519, padding, rsa
+    except ImportError as e:
+        raise ValueError(
+            "Signature verification requires the 'cryptography' package. Install with: pip install cryptography"
+        ) from e
+    if not public_key_pem or not public_key_pem.strip():
+        raise ValueError("Public key PEM must not be empty")
+    try:
+        key = serialization.load_pem_public_key(public_key_pem.encode())
+    except Exception as e:
+        raise ValueError(f"Invalid public key PEM: {e}") from e
+    try:
+        sig_bytes = base64.b64decode(signature_b64, validate=True)
+    except Exception as e:
+        raise ValueError(f"Invalid base64 signature: {e}") from e
+    if isinstance(key, rsa.RSAPublicKey):
+        try:
+            key.verify(sig_bytes, artifact, padding.PKCS1v15(), hashes.SHA256())
+            return True
+        except InvalidSignature:
+            return False
+    if isinstance(key, ed25519.Ed25519PublicKey):
+        try:
+            key.verify(sig_bytes, artifact)
+            return True
+        except InvalidSignature:
+            return False
+    raise ValueError("Unsupported key type for signature verification (RSA or Ed25519 only)")
+
+
+@beartype
+def verify_signature(
+    artifact: _ArtifactInput,
+    signature_b64: str,
+    public_key_pem: str,
+) -> bool:
+    """
+    Verify detached signature over artifact.
+
+    Args:
+        artifact: Raw bytes or path to file.
+        signature_b64: Base64-encoded signature.
+        public_key_pem: PEM-encoded public key.
+
+    Returns:
+        True if signature is valid. False if no signature to verify (empty).
+        Raises ValueError on missing key, invalid format, or verification failure.
+    """
+    if not signature_b64 or not signature_b64.strip():
+        return False
+    artifact_bytes = artifact.read_bytes() if isinstance(artifact, Path) else artifact
+    if not public_key_pem or not public_key_pem.strip():
+        raise ValueError("Public key PEM is required for signature verification")
+    ok = _verify_signature_impl(artifact_bytes, signature_b64.strip(), public_key_pem.strip())
+    if not ok:
+        raise ValueError("Signature verification failed: signature does not match artifact or key")
+    return True