millforge 0.1.0__py3-none-any.whl

millforge/connectors/diagnostics.py

@@ -0,0 +1,189 @@
+"""Connector admission diagnostic contracts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StrictStr,
+    field_validator,
+    model_validator,
+)
+
+from millforge.compiler.diagnostics import detect_secret_candidate
+from millforge.compiler.validators import validate_lower_field_key, validate_utf8_size
+from millforge.contracts import RedactionPolicy, redact_diagnostic_text
+
+MAX_CONNECTOR_DIAGNOSTIC_MESSAGE_UTF8 = 1024
+MAX_CONNECTOR_DIAGNOSTIC_EVIDENCE_UTF8 = 512
+
+
+class ConnectorDiagnosticSeverity(str, Enum):
+    """Closed connector diagnostic severity values."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+class ConnectorDiagnosticPhase(str, Enum):
+    """Closed connector diagnostic phase values."""
+
+    IDENTITY = "identity"
+    DISCOVERY = "discovery"
+    MANIFEST = "manifest"
+    POLICY = "policy"
+    ADMISSION = "admission"
+    DIAGNOSTIC = "diagnostic"
+
+
+class ConnectorDiagnosticCode(str, Enum):
+    """Stable connector diagnostic codes."""
+
+    DISCOVERY_NOT_CATALOG = "MF-C001_DISCOVERY_NOT_CATALOG"
+    IDENTITY_INVALID = "MF-C002_IDENTITY_INVALID"
+    SECRET_MATERIAL = "MF-C003_SECRET_MATERIAL"
+    PROTOCOL_UNSUPPORTED = "MF-C004_PROTOCOL_UNSUPPORTED"
+    TRANSPORT_UNSUPPORTED = "MF-C005_TRANSPORT_UNSUPPORTED"
+    CONNECTOR_ID_MISMATCH = "MF-C006_CONNECTOR_ID_MISMATCH"
+    EXPECTED_IDENTITY_MISMATCH = "MF-C007_EXPECTED_IDENTITY_MISMATCH"
+    DISCOVERY_DUPLICATE_PROVIDER_TOOL = "MF-C008_DISCOVERY_DUPLICATE_PROVIDER_TOOL"
+    ADMITTED_PROVIDER_TOOL_MISSING = "MF-C009_ADMITTED_PROVIDER_TOOL_MISSING"
+    DENIED_TOOL_INVALID = "MF-C010_DENIED_TOOL_INVALID"
+    DUPLICATE_ADMITTED_TOOL = "MF-C011_DUPLICATE_ADMITTED_TOOL"
+    DUPLICATE_MODEL_TOOL_NAME = "MF-C012_DUPLICATE_MODEL_TOOL_NAME"
+    DUPLICATE_IMPLEMENTATION_ID = "MF-C013_DUPLICATE_IMPLEMENTATION_ID"
+    INPUT_SCHEMA_UNSUPPORTED = "MF-C014_INPUT_SCHEMA_UNSUPPORTED"
+    OUTPUT_SCHEMA_UNSUPPORTED = "MF-C015_OUTPUT_SCHEMA_UNSUPPORTED"
+    DESCRIPTION_REQUIRES_OPERATOR_TEXT = "MF-C016_DESCRIPTION_REQUIRES_OPERATOR_TEXT"
+    CAPABILITY_MISSING = "MF-C017_CAPABILITY_MISSING"
+    CAPABILITY_UNKNOWN = "MF-C018_CAPABILITY_UNKNOWN"
+    APPROVAL_POLICY_INVALID = "MF-C019_APPROVAL_POLICY_INVALID"
+    FORBIDDEN_TOOL_ADMITTED = "MF-C020_FORBIDDEN_TOOL_ADMITTED"
+    HASH_MISMATCH = "MF-C021_HASH_MISMATCH"
+
+
+class ConnectorDiagnosticEvidence(BaseModel):
+    """Immutable redacted scalar evidence for connector diagnostics."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    key: StrictStr
+    value: StrictStr
+
+    @field_validator("key")
+    @classmethod
+    def _key_valid(cls, value: str) -> str:
+        return validate_lower_field_key(value)
+
+    @field_validator("value")
+    @classmethod
+    def _value_redacted(cls, value: str) -> str:
+        return redact_connector_text(
+            value, maximum=MAX_CONNECTOR_DIAGNOSTIC_EVIDENCE_UTF8
+        )
+
+
+class ConnectorDiagnostic(BaseModel):
+    """Stable connector diagnostic with redacted evidence."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    code: ConnectorDiagnosticCode
+    severity: ConnectorDiagnosticSeverity
+    phase: ConnectorDiagnosticPhase
+    location: StrictStr | None = None
+    path: StrictStr | None = None
+    message: StrictStr
+    evidence: tuple[ConnectorDiagnosticEvidence, ...] = Field(default_factory=tuple)
+
+    @field_validator("location", "path")
+    @classmethod
+    def _optional_location_valid(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return validate_utf8_size(value, "diagnostic location", 256)
+
+    @field_validator("message")
+    @classmethod
+    def _message_redacted(cls, value: str) -> str:
+        return redact_connector_text(
+            value, maximum=MAX_CONNECTOR_DIAGNOSTIC_MESSAGE_UTF8
+        )
+
+    @model_validator(mode="after")
+    def _location_or_path_required(self) -> ConnectorDiagnostic:
+        if self.location is None and self.path is None:
+            raise ValueError("diagnostic requires location or path")
+        return self
+
+
+def redact_connector_text(value: Any, *, maximum: int) -> str:
+    """Return bounded diagnostic text with secret-looking material redacted."""
+    text = str(value)
+    policy = RedactionPolicy()
+    if detect_secret_candidate(
+        field_path="/connector_diagnostic",
+        field_name="connector_diagnostic",
+        value=text,
+        policy=policy,
+    ):
+        return policy.replacement
+    return validate_utf8_size(
+        redact_diagnostic_text(text, policy=policy), "diagnostic", maximum
+    )
+
+
+def connector_diagnostic(
+    code: ConnectorDiagnosticCode,
+    *,
+    phase: ConnectorDiagnosticPhase,
+    message: str,
+    location: str | None = None,
+    path: str | None = None,
+    severity: ConnectorDiagnosticSeverity = ConnectorDiagnosticSeverity.ERROR,
+    evidence: Mapping[str, Any] | None = None,
+) -> ConnectorDiagnostic:
+    """Build a deterministic connector diagnostic."""
+    fields = tuple(
+        ConnectorDiagnosticEvidence(key=key, value=str(value))
+        for key, value in sorted(
+            (evidence or {}).items(), key=lambda item: str(item[0])
+        )
+    )
+    return ConnectorDiagnostic(
+        code=code,
+        severity=severity,
+        phase=phase,
+        location=location,
+        path=path,
+        message=message,
+        evidence=fields,
+    )
+
+
+def malformed_input_diagnostic(
+    *,
+    phase: ConnectorDiagnosticPhase,
+    model_name: str,
+    path: str = "/",
+    missing_field: str | None = None,
+    code: ConnectorDiagnosticCode = ConnectorDiagnosticCode.IDENTITY_INVALID,
+) -> ConnectorDiagnostic:
+    """Represent malformed raw input without exposing validator exception text."""
+    evidence: dict[str, str] = {"model": model_name}
+    message = "Connector input is malformed."
+    if missing_field is not None:
+        message = "Connector input is missing a required field."
+        evidence["field"] = missing_field
+    return connector_diagnostic(
+        code,
+        phase=phase,
+        path=path,
+        message=message,
+        evidence=evidence,
+    )

millforge/connectors/fake.py

@@ -0,0 +1,66 @@
+"""Deterministic offline connector broker for runtime-boundary tests."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+
+from millforge.connectors.broker import (
+    ConnectorBrokerOutcome,
+    ConnectorInvocationRequest,
+    ConnectorProviderToolEvidence,
+)
+
+FakeConnectorHandler = Callable[[ConnectorInvocationRequest], ConnectorBrokerOutcome]
+
+
+class DeterministicFakeConnectorBroker:
+    """In-memory connector broker keyed by connector ID and provider tool name."""
+
+    def __init__(
+        self,
+        handlers: Mapping[
+            tuple[str, str], ConnectorBrokerOutcome | FakeConnectorHandler
+        ]
+        | None = None,
+        *,
+        provider_evidence: Mapping[tuple[str, str], ConnectorProviderToolEvidence]
+        | None = None,
+    ) -> None:
+        self._handlers = dict(handlers or {})
+        self._provider_evidence = dict(provider_evidence or {})
+        self._requests: list[ConnectorInvocationRequest] = []
+
+    @property
+    def requests(self) -> tuple[ConnectorInvocationRequest, ...]:
+        """Return captured broker requests in invocation order."""
+        return tuple(self._requests)
+
+    def register(
+        self,
+        connector_id: str,
+        provider_tool_name: str,
+        outcome: ConnectorBrokerOutcome | FakeConnectorHandler,
+    ) -> None:
+        """Register a deterministic outcome or handler for a scoped provider tool."""
+        key = (connector_id, provider_tool_name)
+        if key in self._handlers:
+            raise ValueError("duplicate fake connector handler")
+        self._handlers[key] = outcome
+
+    def has_provider_tool(self, connector_id: str, provider_tool_name: str) -> bool:
+        return (connector_id, provider_tool_name) in self._handlers
+
+    def provider_tool_evidence(
+        self,
+        connector_id: str,
+        provider_tool_name: str,
+    ) -> ConnectorProviderToolEvidence | None:
+        return self._provider_evidence.get((connector_id, provider_tool_name))
+
+    def invoke(self, request: ConnectorInvocationRequest) -> ConnectorBrokerOutcome:
+        key = (request.connector_id, request.provider_tool_name)
+        handler = self._handlers[key]
+        self._requests.append(request)
+        if isinstance(handler, ConnectorBrokerOutcome):
+            return handler
+        return handler(request)

millforge/connectors/runtime.py

@@ -0,0 +1,236 @@
+"""Runtime-owned connector admission snapshots."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable
+from types import MappingProxyType
+
+from pydantic import BaseModel, ConfigDict, Field, StrictInt, StrictStr, field_validator
+
+from millforge import IdempotencyClass, SideEffectClass, canonical_json_serialize
+from millforge.compiler.catalogs import ToolCatalogSnapshot
+from millforge.compiler.validators import validate_canonical_tool_id, validate_sha256
+from millforge.connectors.contracts import (
+    ConnectorAdmissionRecord,
+    ConnectorApprovalPolicy,
+)
+from millforge.tools.registry import ToolOutputPolicy, ToolTimeoutPolicy
+
+
+class ConnectorAdmissionSnapshotError(ValueError):
+    """Fail-closed connector admission snapshot construction error."""
+
+
+class ConnectorAdmissionBinding(BaseModel):
+    """Frozen runtime binding from a compiled connector descriptor to admission."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    tool_id: StrictStr
+    tool_version: StrictInt = Field(ge=1)
+    descriptor_sha256: StrictStr
+    connector_id: StrictStr
+    provider_tool_name: StrictStr
+    connector_identity_sha256: StrictStr
+    discovery_snapshot_sha256: StrictStr
+    raw_tool_sha256: StrictStr
+    input_schema_sha256: StrictStr | None = None
+    output_schema_sha256: StrictStr | None = None
+    provider_description_sha256: StrictStr | None = None
+    required_capabilities: tuple[StrictStr, ...]
+    side_effect_class: SideEffectClass
+    idempotency: IdempotencyClass
+    timeout_policy: ToolTimeoutPolicy
+    output_policy: ToolOutputPolicy
+    idempotency_key_policy: StrictStr | None = None
+    approval_policy: ConnectorApprovalPolicy
+    admission_record_sha256: StrictStr
+
+    @field_validator("tool_id")
+    @classmethod
+    def _tool_id_valid(cls, value: str) -> str:
+        return validate_canonical_tool_id(value)
+
+    @field_validator(
+        "descriptor_sha256",
+        "connector_identity_sha256",
+        "discovery_snapshot_sha256",
+        "raw_tool_sha256",
+        "input_schema_sha256",
+        "output_schema_sha256",
+        "provider_description_sha256",
+        "admission_record_sha256",
+    )
+    @classmethod
+    def _hash_valid(cls, value: str | None, info: object) -> str | None:
+        if value is None:
+            return None
+        field_name = getattr(info, "field_name", "sha256")
+        return validate_sha256(value, str(field_name))
+
+
+class ConnectorAdmissionSnapshot:
+    """Deep-frozen runtime snapshot of accepted connector admission records."""
+
+    def __init__(
+        self,
+        *,
+        records: Iterable[ConnectorAdmissionRecord],
+        descriptor_snapshot: ToolCatalogSnapshot,
+    ) -> None:
+        descriptor_keys_by_hash = _descriptor_keys_by_hash(descriptor_snapshot)
+        bindings: dict[tuple[str, int, str], ConnectorAdmissionBinding] = {}
+        for source_record in records:
+            record = ConnectorAdmissionRecord.model_validate(
+                source_record.model_dump(mode="json")
+            )
+            key_prefix = descriptor_keys_by_hash.get(record.descriptor_sha256)
+            if key_prefix is None:
+                raise ConnectorAdmissionSnapshotError(
+                    "connector admission record is stale for descriptor snapshot"
+                )
+            tool_id, tool_version = key_prefix
+            if not is_connector_tool_id(tool_id):
+                raise ConnectorAdmissionSnapshotError(
+                    "connector admission record targets a non-connector descriptor"
+                )
+            key = (tool_id, tool_version, record.descriptor_sha256)
+            if key in bindings:
+                raise ConnectorAdmissionSnapshotError(
+                    "duplicate connector admission record"
+                )
+            descriptor_entry = descriptor_snapshot.resolve_exact(
+                tool_id, tool_version
+            ).entry
+            if descriptor_entry is None:
+                raise ConnectorAdmissionSnapshotError(
+                    "connector admission record is stale for descriptor snapshot"
+                )
+            _validate_record_descriptor_consistency(record, descriptor_entry)
+            bindings[key] = ConnectorAdmissionBinding(
+                tool_id=tool_id,
+                tool_version=tool_version,
+                descriptor_sha256=record.descriptor_sha256,
+                connector_id=record.connector_id,
+                provider_tool_name=record.provider_tool_name,
+                connector_identity_sha256=record.connector_identity_sha256,
+                discovery_snapshot_sha256=record.discovery_snapshot_sha256,
+                raw_tool_sha256=record.raw_tool_sha256,
+                input_schema_sha256=record.input_schema_sha256,
+                output_schema_sha256=record.output_schema_sha256,
+                provider_description_sha256=record.provider_description_sha256,
+                required_capabilities=record.required_capabilities,
+                side_effect_class=record.side_effect_class,
+                idempotency=record.idempotency,
+                timeout_policy=record.timeout_policy,
+                output_policy=record.output_policy,
+                idempotency_key_policy=record.idempotency_key_policy,
+                approval_policy=record.approval_policy,
+                admission_record_sha256=record.admission_record_sha256,
+            )
+        self._bindings = MappingProxyType(dict(sorted(bindings.items())))
+        self._snapshot_sha256 = _snapshot_sha256(self._bindings.values())
+
+    @property
+    def snapshot_sha256(self) -> str:
+        """Return a deterministic hash of accepted connector admission bindings."""
+        return self._snapshot_sha256
+
+    @property
+    def bindings(self) -> tuple[ConnectorAdmissionBinding, ...]:
+        """Return frozen connector admission bindings in deterministic order."""
+        return tuple(self._bindings.values())
+
+    def resolve(
+        self, tool_id: str, tool_version: int, descriptor_sha256: str
+    ) -> ConnectorAdmissionBinding | None:
+        """Resolve an exact compiled connector descriptor binding."""
+        return self._bindings.get((tool_id, tool_version, descriptor_sha256))
+
+    def require(
+        self, tool_id: str, tool_version: int, descriptor_sha256: str
+    ) -> ConnectorAdmissionBinding:
+        """Resolve an exact connector binding or fail construction."""
+        binding = self.resolve(tool_id, tool_version, descriptor_sha256)
+        if binding is None:
+            raise ConnectorAdmissionSnapshotError(
+                "compiled connector descriptor is missing admission record"
+            )
+        return binding
+
+
+def is_connector_tool_id(tool_id: str) -> bool:
+    """Return whether a tool id belongs to the connector descriptor namespace."""
+    return tool_id.startswith("connector.")
+
+
+def _descriptor_keys_by_hash(
+    descriptor_snapshot: ToolCatalogSnapshot,
+) -> dict[str, tuple[str, int]]:
+    records = getattr(descriptor_snapshot, "descriptor_hash_records", None)
+    if records is None:
+        raise ConnectorAdmissionSnapshotError(
+            "descriptor snapshot does not expose descriptor hash records"
+        )
+    keys_by_hash: dict[str, tuple[str, int]] = {}
+    for record in records:
+        descriptor_sha256 = record.descriptor_sha256
+        key = (record.tool_id, record.tool_version)
+        if descriptor_sha256 in keys_by_hash:
+            raise ConnectorAdmissionSnapshotError("duplicate descriptor hash record")
+        keys_by_hash[descriptor_sha256] = key
+    return keys_by_hash
+
+
+def _validate_record_descriptor_consistency(
+    record: ConnectorAdmissionRecord, descriptor_entry: object
+) -> None:
+    expected = {
+        "descriptor_sha256": getattr(descriptor_entry, "descriptor_sha256", None),
+        "required_capabilities": tuple(
+            getattr(descriptor_entry, "required_capabilities", ())
+        ),
+        "side_effect_class": getattr(descriptor_entry, "side_effect_class", None),
+        "idempotency": getattr(descriptor_entry, "idempotency", None),
+        "timeout_policy": getattr(descriptor_entry, "timeout_policy", None),
+        "output_policy": getattr(descriptor_entry, "output_policy", None),
+        "idempotency_key_policy": (
+            "call_id"
+            if getattr(descriptor_entry, "idempotency", None)
+            is IdempotencyClass.IDEMPOTENT_WITH_KEY
+            else None
+        ),
+    }
+    actual = {
+        "descriptor_sha256": record.descriptor_sha256,
+        "required_capabilities": record.required_capabilities,
+        "side_effect_class": record.side_effect_class,
+        "idempotency": record.idempotency,
+        "timeout_policy": record.timeout_policy,
+        "output_policy": record.output_policy,
+        "idempotency_key_policy": record.idempotency_key_policy,
+    }
+    for field, expected_value in expected.items():
+        if actual[field] != expected_value:
+            raise ConnectorAdmissionSnapshotError(
+                f"connector admission record is descriptor-inconsistent: {field}"
+            )
+
+
+def _snapshot_sha256(bindings: Iterable[ConnectorAdmissionBinding]) -> str:
+    payload = {
+        "kind": "millforge.connector.admission_snapshot.v1",
+        "bindings": [
+            binding.model_dump(mode="json")
+            for binding in sorted(
+                bindings,
+                key=lambda item: (
+                    item.tool_id,
+                    item.tool_version,
+                    item.descriptor_sha256,
+                ),
+            )
+        ],
+    }
+    return hashlib.sha256(canonical_json_serialize(payload).encode("utf-8")).hexdigest()