controlloop 0.1.0__py3-none-any.whl

controlloop/__init__.py

@@ -0,0 +1,16 @@
+"""ControlLoop Community CLI."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def _distribution_version() -> str:
+    """Return the installed version or a safe source-tree fallback."""
+    try:
+        return version("controlloop")
+    except PackageNotFoundError:
+        return "0.0.0+uninstalled"
+
+
+__version__ = _distribution_version()
+
+__all__ = ["__version__"]

controlloop/__main__.py

@@ -0,0 +1,6 @@
+"""Run ControlLoop with ``python -m controlloop``."""
+
+from controlloop.cli import main
+
+if __name__ == "__main__":
+    main()

controlloop/acbom/__init__.py

@@ -0,0 +1,93 @@
+"""Canonical Agent Capability Bill of Materials models."""
+
+from controlloop.acbom.completeness import (
+    INCOMPLETE_DIAGNOSTIC_REGISTRY,
+    completeness_summary,
+    incomplete_diagnostic,
+)
+from controlloop.acbom.identity import (
+    IDENTITY_VERSION,
+    EdgeIdentityMaterial,
+    NodeIdentityMaterial,
+    SemanticIdentity,
+    edge_id,
+    node_id,
+)
+from controlloop.acbom.models import (
+    ACBOMDocument,
+    Confidence,
+    Diagnostic,
+    DiagnosticSeverity,
+    Edge,
+    EdgeStatus,
+    EdgeType,
+    Evidence,
+    Generator,
+    KnownBoolean,
+    Node,
+    NodeType,
+    Repository,
+    SecurityAttributes,
+    Sensitivity,
+    StandardIdentifier,
+)
+from controlloop.acbom.serialization import (
+    CanonicalizationError,
+    EdgeMergeConflictError,
+    NodeMergeConflictError,
+    canonical_json_bytes,
+    canonicalize_document,
+    compute_digest,
+    merge_duplicate_edges,
+    merge_duplicate_nodes,
+    serialize_document,
+    with_digest,
+)
+from controlloop.acbom.versioning import (
+    CURRENT_SCHEMA_VERSION,
+    IncompatibleSchemaVersionError,
+    check_schema_version_compatible,
+    load_acbom_document,
+)
+
+__all__ = [
+    "CURRENT_SCHEMA_VERSION",
+    "IDENTITY_VERSION",
+    "INCOMPLETE_DIAGNOSTIC_REGISTRY",
+    "ACBOMDocument",
+    "CanonicalizationError",
+    "Confidence",
+    "Diagnostic",
+    "DiagnosticSeverity",
+    "Edge",
+    "EdgeIdentityMaterial",
+    "EdgeMergeConflictError",
+    "EdgeStatus",
+    "EdgeType",
+    "Evidence",
+    "Generator",
+    "IncompatibleSchemaVersionError",
+    "KnownBoolean",
+    "Node",
+    "NodeIdentityMaterial",
+    "NodeMergeConflictError",
+    "NodeType",
+    "Repository",
+    "SecurityAttributes",
+    "SemanticIdentity",
+    "Sensitivity",
+    "StandardIdentifier",
+    "canonical_json_bytes",
+    "canonicalize_document",
+    "check_schema_version_compatible",
+    "completeness_summary",
+    "compute_digest",
+    "edge_id",
+    "incomplete_diagnostic",
+    "load_acbom_document",
+    "merge_duplicate_edges",
+    "merge_duplicate_nodes",
+    "node_id",
+    "serialize_document",
+    "with_digest",
+]

controlloop/acbom/completeness.py

@@ -0,0 +1,117 @@
+"""Unknown and incomplete analysis representation for canonical ACBOMs.
+
+Dynamic or unsupported behavior is represented as an explicit unknown --
+never omitted silently, since a silently dropped capability produces a
+confident pass, the worst failure this product can have. This module
+mirrors `controlloop.repository`'s `DIAGNOSTIC_REGISTRY`/`summarize_skips`
+pattern at the canonical ACBOM layer: a closed, documented code registry,
+a constructor enforcing the shape, and a deterministic summary view.
+
+No new schema surface is introduced. `Diagnostic.incomplete` and
+`Diagnostic.confidence` already exist on the canonical model; a
+completeness summary is a filtered, sorted view over an
+`ACBOMDocument`'s existing `diagnostics`, not new stored state.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from controlloop.acbom.models import (
+    ACBOMDocument,
+    Confidence,
+    Diagnostic,
+    DiagnosticCode,
+    DiagnosticSeverity,
+    EvidenceCollection,
+    SafeText,
+)
+
+_UNRESOLVED_REFERENCE_CODE = "INCOMPLETE-UNRESOLVED-REFERENCE"
+_DYNAMIC_REGISTRATION_CODE = "INCOMPLETE-DYNAMIC-REGISTRATION"
+_UNPARSED_REGION_CODE = "INCOMPLETE-UNPARSED-REGION"
+_BOUND_EXCEEDED_CODE = "INCOMPLETE-BOUND-EXCEEDED"
+_ADAPTER_FAILURE_CODE = "INCOMPLETE-ADAPTER-FAILURE"
+_UNVERIFIED_DECLARATION_CODE = "INCOMPLETE-UNVERIFIED-DECLARATION"
+_CYCLE_DETECTED_CODE = "INCOMPLETE-CYCLE-DETECTED"
+
+INCOMPLETE_DIAGNOSTIC_REGISTRY: Mapping[str, str] = {
+    _UNRESOLVED_REFERENCE_CODE: (
+        "A reference to a capability, tool, or identity could not be "
+        "resolved to a concrete node."
+    ),
+    _DYNAMIC_REGISTRATION_CODE: (
+        "A tool, agent, or capability is registered at runtime and "
+        "cannot be proven statically."
+    ),
+    _UNPARSED_REGION_CODE: (
+        "A region of an otherwise-supported input could not be parsed."
+    ),
+    _BOUND_EXCEEDED_CODE: (
+        "Analysis stopped because a configured resource or depth bound "
+        "was reached before discovery completed."
+    ),
+    _ADAPTER_FAILURE_CODE: (
+        "An adapter raised while detecting or discovering evidence, and "
+        "was isolated so the rest of the scan could continue."
+    ),
+    _UNVERIFIED_DECLARATION_CODE: (
+        "A human-authored manifest declaration names a capability that "
+        "discovered evidence could not corroborate."
+    ),
+    _CYCLE_DETECTED_CODE: (
+        "A graph traversal reached a node already present earlier on the "
+        "same path and stopped there, rather than looping or reporting "
+        "an arbitrarily long path through the cycle."
+    ),
+}
+
+
+def incomplete_diagnostic(
+    *,
+    code: DiagnosticCode,
+    message: SafeText,
+    evidence: EvidenceCollection,
+) -> Diagnostic:
+    """Return a `Diagnostic` representing an explicit unknown (REQ-1).
+
+    `code` must be a member of `INCOMPLETE_DIAGNOSTIC_REGISTRY`. Always
+    `incomplete=True` and `confidence=Confidence.UNKNOWN` -- an
+    incompleteness diagnostic can never claim confident knowledge of the
+    very thing it reports as unresolved.
+    """
+
+    if code not in INCOMPLETE_DIAGNOSTIC_REGISTRY:
+        raise ValueError(f"{code!r} is not a registered incompleteness code")
+
+    return Diagnostic(
+        code=code,
+        severity=DiagnosticSeverity.WARNING,
+        message=message,
+        confidence=Confidence.UNKNOWN,
+        incomplete=True,
+        evidence=evidence,
+    )
+
+
+def completeness_summary(document: ACBOMDocument) -> tuple[Diagnostic, ...]:
+    """Return every reason `document`'s analysis was incomplete (REQ-2).
+
+    A deterministic, sorted view over `document.diagnostics` filtered to
+    `incomplete=True` -- independent of the input collection's order, the
+    same guarantee `repository.summarize_skips` already keeps for
+    repository-traversal diagnostics.
+    """
+
+    incomplete = [
+        diagnostic for diagnostic in document.diagnostics if diagnostic.incomplete
+    ]
+    return tuple(
+        sorted(
+            incomplete,
+            key=lambda diagnostic: (
+                diagnostic.evidence[0].path or "",
+                diagnostic.code,
+            ),
+        )
+    )

controlloop/acbom/identity.py

@@ -0,0 +1,210 @@
+"""Stable, privacy-preserving identifiers for canonical ACBOM components."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping
+from typing import Annotated, Any, ClassVar, Self
+
+from pydantic import BaseModel, ConfigDict, StringConstraints, model_validator
+
+from controlloop.acbom.models import (
+    EdgeId,
+    EdgeType,
+    NodeId,
+    NodeType,
+    RelativePath,
+    SafeIdentifier,
+)
+
+IDENTITY_VERSION = 1
+_EDGE_NAMESPACE = "controlloop.edge"
+
+IdentityString = Annotated[
+    str,
+    StringConstraints(
+        strict=True,
+        min_length=1,
+        max_length=512,
+        pattern=r"^[^\x00-\x1f\x7f]*$",
+    ),
+]
+
+_PROHIBITED_FIELD_CATEGORIES: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("private key", ("privatekey",)),
+    (
+        "environment value",
+        (
+            "environmentvalue",
+            "environmentvariablevalue",
+            "envvalue",
+            "envvarvalue",
+        ),
+    ),
+    ("source content", ("sourcecontent", "sourcecode", "rawsource")),
+    ("credential", ("credential",)),
+    ("password", ("password", "passwd")),
+    ("secret", ("secret",)),
+    ("token", ("token",)),
+)
+_EXCLUDED_FIELD_CATEGORIES: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("presentation", ("display", "label", "description")),
+    ("evidence", ("evidence", "confidence", "linenumber", "line")),
+    ("timestamp", ("timestamp", "createdat", "updatedat")),
+    ("version", ("schemaversion", "generatorversion")),
+    ("security attribute", ("securityattribute",)),
+)
+
+
+def _normalized_field_name(field_name: str) -> str:
+    return re.sub(r"[^a-z0-9]", "", field_name.casefold())
+
+
+def _field_category(field_name: object) -> tuple[str, str] | None:
+    if not isinstance(field_name, str):
+        return ("unsupported", "unsupported")
+
+    normalized = _normalized_field_name(field_name)
+    for category, markers in _PROHIBITED_FIELD_CATEGORIES:
+        if any(marker in normalized for marker in markers):
+            return ("prohibited", category)
+    for category, markers in _EXCLUDED_FIELD_CATEGORIES:
+        if any(marker in normalized for marker in markers):
+            return ("excluded", category)
+    return None
+
+
+class _IdentityModel(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=True,
+        hide_input_in_errors=True,
+        strict=True,
+    )
+
+    _allowed_fields: ClassVar[frozenset[str]]
+
+    @model_validator(mode="before")
+    @classmethod
+    def reject_unapproved_fields(cls, value: Any) -> Any:
+        if not isinstance(value, Mapping):
+            return value
+
+        for field_name in value:
+            if field_name in cls._allowed_fields:
+                continue
+            category = _field_category(field_name)
+            if category is None:
+                raise ValueError("unsupported identity field category")
+            disposition, safe_category = category
+            raise ValueError(f"{disposition} identity field category: {safe_category}")
+        return value
+
+
+class SemanticIdentity(_IdentityModel):
+    """Allowlisted semantic identity for the canonical ACBOM contract."""
+
+    _allowed_fields = frozenset({"identifier", "source_path", "in_document_key"})
+
+    identifier: IdentityString | None = None
+    source_path: RelativePath | None = None
+    in_document_key: IdentityString | None = None
+
+    @model_validator(mode="after")
+    def validate_identity_shape(self) -> Self:
+        uses_identifier = self.identifier is not None
+        uses_adapter_fallback = (
+            self.source_path is not None and self.in_document_key is not None
+        )
+        if uses_identifier == uses_adapter_fallback:
+            raise ValueError(
+                "semantic identity requires exactly one approved identity category"
+            )
+        if (self.source_path is None) != (self.in_document_key is None):
+            raise ValueError(
+                "adapter fallback identity requires path and in-document key"
+            )
+        return self
+
+
+class NodeIdentityMaterial(_IdentityModel):
+    """Typed node identity material accepted by the hashing boundary."""
+
+    _allowed_fields = frozenset({"node_type", "namespace", "semantic_identity"})
+
+    node_type: NodeType
+    namespace: SafeIdentifier
+    semantic_identity: SemanticIdentity
+
+
+class EdgeIdentityMaterial(_IdentityModel):
+    """Typed edge identity material accepted by the hashing boundary."""
+
+    _allowed_fields = frozenset(
+        {
+            "relationship_type",
+            "source_id",
+            "target_id",
+            "relationship_discriminator",
+        }
+    )
+
+    relationship_type: EdgeType
+    source_id: NodeId
+    target_id: NodeId
+    relationship_discriminator: IdentityString
+
+
+def _canonical_identity_bytes(
+    *,
+    node_type: str,
+    namespace: str,
+    semantic_identity: dict[str, object],
+) -> bytes:
+    payload = {
+        "identity_version": IDENTITY_VERSION,
+        "namespace": namespace,
+        "node_type": node_type,
+        "semantic_identity": semantic_identity,
+    }
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        allow_nan=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def node_id(material: NodeIdentityMaterial) -> NodeId:
+    """Return the stable canonical ID for validated node identity material."""
+
+    canonical_bytes = _canonical_identity_bytes(
+        node_type=material.node_type.value,
+        namespace=material.namespace,
+        semantic_identity=material.semantic_identity.model_dump(
+            mode="json",
+            exclude_none=True,
+        ),
+    )
+    digest = hashlib.sha256(canonical_bytes).hexdigest()
+    return f"clp:{material.node_type.value}:sha256:{digest}"
+
+
+def edge_id(material: EdgeIdentityMaterial) -> EdgeId:
+    """Return the stable canonical ID for validated edge identity material."""
+
+    canonical_bytes = _canonical_identity_bytes(
+        node_type="edge",
+        namespace=_EDGE_NAMESPACE,
+        semantic_identity={
+            "relationship_discriminator": material.relationship_discriminator,
+            "relationship_type": material.relationship_type.value,
+            "source_id": material.source_id,
+            "target_id": material.target_id,
+        },
+    )
+    digest = hashlib.sha256(canonical_bytes).hexdigest()
+    return f"clp:edge:sha256:{digest}"