cmgl 1.1.0__py3-none-any.whl

cmgl/__init__.py

@@ -0,0 +1,269 @@
+from cmgl.admission import RetrievalFilterResult, candidate_from_event, filter_retrieval
+from cmgl.authority import (
+    StrictAuthorityVerifier,
+    authorize_bundle,
+    authorize_request,
+    make_authority_bundle,
+    make_authority_evidence_bundle,
+    make_authority_receipt,
+    make_declared_scope,
+    make_protected_action_request,
+)
+from cmgl.compression import (
+    CompressionProbeSuite,
+    audit_compression_certificate,
+    compression_metrics,
+    make_compression_certificate,
+)
+from cmgl.config import (
+    AuthorityConfig,
+    CMGLConfig,
+    LedgerConfig,
+    PolicyConfig,
+    load_config,
+)
+from cmgl.conformance import audit_ledger_conformance
+from cmgl.digest import sha256_digest
+from cmgl.evidence import (
+    build_evidence_manifest,
+    build_input_set_manifest,
+    build_promotion_evidence_bundle,
+    build_replay_evidence,
+    versioned_ref_from_event,
+)
+from cmgl.guarded import GuardedMemoryBackend
+from cmgl.layer import GovernanceLayer
+from cmgl.ledger import (
+    AppendOnlyLedger,
+    LedgerRecord,
+    LedgerVerificationResult,
+    make_duplicate_policy_receipt,
+    make_schema_migration_record,
+)
+from cmgl.models import (
+    AbsenceNoticeType,
+    ActivePromotionReceipt,
+    AdapterOperationReceipt,
+    AdapterOperationStatus,
+    AdmissionDecision,
+    AuthorityBundle,
+    AuthorityEvidenceBundle,
+    AuthorityReceipt,
+    BackendName,
+    ChallengeStatus,
+    CompressionAuditReport,
+    CompressionBridgeProbe,
+    CompressionCertificate,
+    CompressionDeploymentProbe,
+    CompressionFailureClass,
+    CompressionGluingProbe,
+    ConformanceFinding,
+    ConformanceLevel,
+    ConformanceProfile,
+    ConformanceReport,
+    ConformanceSeverity,
+    ContaminationAuditReport,
+    ContaminationContext,
+    ContaminationLane,
+    ContaminationStateReplay,
+    CurrentMemoryView,
+    DeclaredScope,
+    DuplicatePolicyReceipt,
+    EvidenceBindingReport,
+    EvidenceManifest,
+    ExternalMemoryRef,
+    GovernanceProfile,
+    GovernanceReceiptBundle,
+    InputSetManifest,
+    LeaseReceipt,
+    LedgerAppendReceipt,
+    LedgerIntegrityReceipt,
+    LedgerLineStatus,
+    MemoryCandidate,
+    MemoryChallengeRecord,
+    MemoryEvent,
+    MemoryEventType,
+    MemoryGovernanceEvidenceContract,
+    MemoryRevision,
+    MemoryStateSnapshot,
+    MemoryStatus,
+    MemoryTelemetryEvent,
+    MetricResult,
+    MetricStatus,
+    ObligationGraph,
+    ObligationStatus,
+    PromotionEvidenceBundle,
+    PromotionReceipt,
+    ProtectedAction,
+    ProtectedActionRequest,
+    QuarantineRecord,
+    RationalValue,
+    ReceiptObligation,
+    RecordAbsenceNotice,
+    ReplayEvidence,
+    ReportTermBinding,
+    RetrievalDecision,
+    RollbackReceipt,
+    RollbackSnapshot,
+    SchemaMigrationRecord,
+    SemanticRule,
+    ShadowTrialReceipt,
+    TelemetryAuditReport,
+    TelemetryEventOutcome,
+    TelemetryEventType,
+    TelemetryIngestResult,
+    TelemetryLineDiagnostic,
+    TelemetryOutcomeStatus,
+    TelemetryReplayReport,
+    TelemetryStateReplay,
+    VerificationWitness,
+    VersionedMemoryRef,
+    WorkflowBottleneckReport,
+    WorkflowEvidenceSet,
+    WorkflowLayer,
+)
+from cmgl.pipeline import PromotionPipeline, PromotionPipelineResult
+from cmgl.policy import AdmissionPolicy
+from cmgl.receipt_verifier import PromotionVerifier
+from cmgl.state import current_memory_view_from_events, current_memory_view_from_ledger
+from cmgl.stress import SharedMemoryStressResult, shared_memory_stress_fixture
+from cmgl.telemetry_ingest import ingest_telemetry_jsonl
+from cmgl.telemetry_replay import replay_telemetry_jsonl
+from cmgl.workflow import (
+    make_memory_governance_evidence_contract,
+    make_workflow_evidence_set,
+    workflow_report_from_evidence,
+)
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "AbsenceNoticeType",
+    "ActivePromotionReceipt",
+    "AdapterOperationReceipt",
+    "AdapterOperationStatus",
+    "AdmissionDecision",
+    "AdmissionPolicy",
+    "AppendOnlyLedger",
+    "AuthorityBundle",
+    "AuthorityConfig",
+    "AuthorityEvidenceBundle",
+    "AuthorityReceipt",
+    "BackendName",
+    "CMGLConfig",
+    "ChallengeStatus",
+    "CompressionAuditReport",
+    "CompressionBridgeProbe",
+    "CompressionCertificate",
+    "CompressionDeploymentProbe",
+    "CompressionFailureClass",
+    "CompressionGluingProbe",
+    "CompressionProbeSuite",
+    "ConformanceFinding",
+    "ConformanceLevel",
+    "ConformanceProfile",
+    "ConformanceReport",
+    "ConformanceSeverity",
+    "ContaminationAuditReport",
+    "ContaminationContext",
+    "ContaminationLane",
+    "ContaminationStateReplay",
+    "CurrentMemoryView",
+    "DeclaredScope",
+    "DuplicatePolicyReceipt",
+    "EvidenceBindingReport",
+    "EvidenceManifest",
+    "ExternalMemoryRef",
+    "GovernanceLayer",
+    "GovernanceProfile",
+    "GovernanceReceiptBundle",
+    "GuardedMemoryBackend",
+    "InputSetManifest",
+    "LeaseReceipt",
+    "LedgerAppendReceipt",
+    "LedgerConfig",
+    "LedgerIntegrityReceipt",
+    "LedgerLineStatus",
+    "LedgerRecord",
+    "LedgerVerificationResult",
+    "MemoryCandidate",
+    "MemoryChallengeRecord",
+    "MemoryEvent",
+    "MemoryEventType",
+    "MemoryGovernanceEvidenceContract",
+    "MemoryRevision",
+    "MemoryStateSnapshot",
+    "MemoryStatus",
+    "MemoryTelemetryEvent",
+    "MetricResult",
+    "MetricStatus",
+    "ObligationGraph",
+    "ObligationStatus",
+    "PolicyConfig",
+    "PromotionEvidenceBundle",
+    "PromotionPipeline",
+    "PromotionPipelineResult",
+    "PromotionReceipt",
+    "PromotionVerifier",
+    "ProtectedAction",
+    "ProtectedActionRequest",
+    "QuarantineRecord",
+    "RationalValue",
+    "ReceiptObligation",
+    "RecordAbsenceNotice",
+    "ReplayEvidence",
+    "ReportTermBinding",
+    "RetrievalDecision",
+    "RetrievalFilterResult",
+    "RollbackReceipt",
+    "RollbackSnapshot",
+    "SchemaMigrationRecord",
+    "SemanticRule",
+    "ShadowTrialReceipt",
+    "SharedMemoryStressResult",
+    "StrictAuthorityVerifier",
+    "TelemetryAuditReport",
+    "TelemetryEventOutcome",
+    "TelemetryEventType",
+    "TelemetryIngestResult",
+    "TelemetryLineDiagnostic",
+    "TelemetryOutcomeStatus",
+    "TelemetryReplayReport",
+    "TelemetryStateReplay",
+    "VerificationWitness",
+    "VersionedMemoryRef",
+    "WorkflowBottleneckReport",
+    "WorkflowEvidenceSet",
+    "WorkflowLayer",
+    "__version__",
+    "audit_compression_certificate",
+    "audit_ledger_conformance",
+    "authorize_bundle",
+    "authorize_request",
+    "build_evidence_manifest",
+    "build_input_set_manifest",
+    "build_promotion_evidence_bundle",
+    "build_replay_evidence",
+    "candidate_from_event",
+    "compression_metrics",
+    "current_memory_view_from_events",
+    "current_memory_view_from_ledger",
+    "filter_retrieval",
+    "ingest_telemetry_jsonl",
+    "load_config",
+    "make_authority_bundle",
+    "make_authority_evidence_bundle",
+    "make_authority_receipt",
+    "make_compression_certificate",
+    "make_declared_scope",
+    "make_duplicate_policy_receipt",
+    "make_memory_governance_evidence_contract",
+    "make_protected_action_request",
+    "make_schema_migration_record",
+    "make_workflow_evidence_set",
+    "replay_telemetry_jsonl",
+    "sha256_digest",
+    "shared_memory_stress_fixture",
+    "versioned_ref_from_event",
+    "workflow_report_from_evidence",
+]

cmgl/__main__.py

@@ -0,0 +1,4 @@
+from cmgl.cli import app
+
+if __name__ == "__main__":
+    app()

cmgl/absence.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from uuid import uuid4
+
+from cmgl.digest import sha256_digest
+from cmgl.models import AbsenceNoticeType, RecordAbsenceNotice
+from cmgl.time import now_utc
+
+
+def make_record_absence_notice(
+    *,
+    notice_type: AbsenceNoticeType,
+    memory_id: str | None = None,
+    missing_record: object | None = None,
+    disclosure: object | None = None,
+    reason_codes: list[str] | None = None,
+) -> RecordAbsenceNotice:
+    default_code = f"absence.{notice_type.value}"
+    body = {
+        "schema_version": "cmgl.record_absence_notice.v1",
+        "notice_id": f"absence:{uuid4()}",
+        "notice_type": notice_type,
+        "memory_id": memory_id,
+        "missing_record_digest": None if missing_record is None else sha256_digest(missing_record),
+        "disclosure_digest": None if disclosure is None else sha256_digest(disclosure),
+        "reason_codes": list(reason_codes or [default_code]),
+        "timestamp": now_utc(),
+    }
+    return RecordAbsenceNotice(**body, notice_digest=sha256_digest(body))

cmgl/adapters/__init__.py

@@ -0,0 +1,3 @@
+"""Optional safe integration shims for external memory frameworks."""
+
+__all__ = ["binding", "common", "graphiti", "langgraph", "langmem", "mem0"]

cmgl/adapters/binding.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from datetime import datetime
+from enum import Enum
+from typing import Any, Literal, cast
+from uuid import uuid4
+
+from pydantic import BaseModel
+
+from cmgl.adapters.common import object_to_mapping
+from cmgl.digest import sha256_digest
+from cmgl.lifecycle import make_quarantine_record
+from cmgl.models import (
+    AdapterOperationReceipt,
+    AdapterOperationStatus,
+    AdmissionDecision,
+    BackendName,
+    ExternalMemoryRef,
+    GovernanceReceiptBundle,
+    MemoryEvent,
+)
+from cmgl.pipeline import PromotionPipelineResult
+from cmgl.time import now_utc
+
+_EXTERNAL_ID_KEYS = (
+    "id",
+    "memory_id",
+    "uuid",
+    "episode_uuid",
+    "episode_id",
+    "node_uuid",
+    "edge_uuid",
+    "source_node_uuid",
+    "target_node_uuid",
+)
+_EXTERNAL_UPDATE_KEYS = (
+    "memory_update_id",
+    "update_id",
+    "revision_id",
+    "version",
+    "updated_at",
+    "created_at",
+)
+
+
+def external_ref_from_result(
+    result: Any,
+    *,
+    event: MemoryEvent,
+    backend: BackendName | str,
+    namespace: str | None = None,
+    external_id: str | None = None,
+    external_update_id: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> ExternalMemoryRef:
+    """Create a stable CMGL-to-external-memory binding from an SDK result."""
+
+    mapping = object_to_mapping(result)
+    payload_digest = sha256_digest(_jsonable(result))
+    resolved_external_id = external_id or _first_present(mapping, _EXTERNAL_ID_KEYS)
+    resolved_update_id = external_update_id or _first_present(mapping, _EXTERNAL_UPDATE_KEYS)
+    body = {
+        "schema_version": "cmgl.external_memory_ref.v1",
+        "backend": backend,
+        "external_id": str(resolved_external_id or payload_digest),
+        "external_update_id": None if resolved_update_id is None else str(resolved_update_id),
+        "cmgl_memory_id": event.memory_id,
+        "cmgl_memory_update_id": event.memory_update_id,
+        "authority_scope": event.authority_scope,
+        "content_digest": event.content_digest,
+        "source_payload_digest": payload_digest,
+        "namespace": namespace,
+        "metadata": dict(metadata or {}),
+        "timestamp": now_utc(),
+    }
+    return ExternalMemoryRef(**body)
+
+
+def make_adapter_operation_receipt(
+    *,
+    backend: BackendName | str,
+    operation: Literal["write", "update", "delete", "retrieve"],
+    event: MemoryEvent | None = None,
+    status: AdapterOperationStatus,
+    decision: AdmissionDecision,
+    external_ref: ExternalMemoryRef | None = None,
+    reason_codes: list[str] | None = None,
+    error: BaseException | None = None,
+    timestamp: datetime | None = None,
+) -> AdapterOperationReceipt:
+    """Build a digest-bound adapter operation receipt."""
+
+    body = {
+        "schema_version": "cmgl.adapter_operation_receipt.v1",
+        "operation_id": f"adapter-op:{uuid4()}",
+        "backend": backend,
+        "operation": operation,
+        "status": status,
+        "decision": decision,
+        "cmgl_memory_id": None if event is None else event.memory_id,
+        "cmgl_memory_update_id": None if event is None else event.memory_update_id,
+        "external_ref": external_ref,
+        "reason_codes": list(reason_codes or []),
+        "error_type": None if error is None else type(error).__name__,
+        "error_message": None if error is None else _safe_error_message(error),
+        "timestamp": timestamp or now_utc(),
+    }
+    return AdapterOperationReceipt(**body, receipt_digest=sha256_digest(body))
+
+
+def success_reason(operation: Literal["write", "update", "delete", "retrieve"]) -> str:
+    return f"adapter.external_{operation}_succeeded"
+
+
+def append_adapter_receipt(
+    layer: Any,
+    receipt: AdapterOperationReceipt,
+    *,
+    quarantine_on_failure: bool = True,
+) -> str | None:
+    """Append adapter operation evidence and optionally quarantine failures."""
+
+    layer.ledger.append_with_receipt(
+        "adapter_operation_receipt",
+        receipt,
+        persist_receipt=layer.config.ledger.persist_append_receipts,
+    )
+    if receipt.status != AdapterOperationStatus.FAILED or not quarantine_on_failure:
+        return None
+    quarantine = make_quarantine_record(
+        target=receipt,
+        target_type="adapter_operation_receipt",
+        reason_codes=["adapter.external_persistence_failed"],
+    )
+    record, _ = layer.ledger.append_with_receipt(
+        "quarantine_record",
+        quarantine,
+        persist_receipt=layer.config.ledger.persist_append_receipts,
+    )
+    return cast(str, record.record_digest)
+
+
+def bundle_with_adapter_receipt(
+    layer: Any,
+    result: PromotionPipelineResult,
+    *,
+    adapter_receipt: AdapterOperationReceipt,
+    backend_result: Any | None = None,
+    quarantine_record_digest: str | None = None,
+) -> GovernanceReceiptBundle:
+    bundle = GovernanceReceiptBundle.model_validate(
+        layer.receipt_bundle(
+            result,
+            backend_result=backend_result,
+            adapter_operation_receipt=adapter_receipt,
+        )
+    )
+    if quarantine_record_digest is None:
+        return bundle
+    body = bundle.model_dump()
+    body["quarantine_record_digest"] = quarantine_record_digest
+    body.pop("bundle_digest", None)
+    return GovernanceReceiptBundle(**body, bundle_digest=sha256_digest(body))
+
+
+def has_successful_binding(layer: Any, memory_id: str) -> bool:
+    """Return true when the ledger has a prior succeeded external binding."""
+
+    for record in layer.ledger.iter_records():
+        if record.record_type != "adapter_operation_receipt":
+            continue
+        payload = record.payload
+        if not isinstance(payload, Mapping):
+            continue
+        if payload.get("status") != AdapterOperationStatus.SUCCEEDED.value:
+            continue
+        external_ref = payload.get("external_ref")
+        if isinstance(external_ref, Mapping) and external_ref.get("cmgl_memory_id") == memory_id:
+            return True
+    return False
+
+
+def _first_present(mapping: Mapping[str, Any], keys: Sequence[str]) -> Any:
+    for key in keys:
+        value = mapping.get(key)
+        if value not in (None, ""):
+            return value
+    return None
+
+
+def _jsonable(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, Mapping):
+        return {str(key): _jsonable(item) for key, item in value.items()}
+    if isinstance(value, Sequence) and not isinstance(value, str | bytes):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, str | int | float | bool) or value is None:
+        return value
+    return str(value)
+
+
+def _safe_error_message(error: BaseException) -> str:
+    message = str(error).replace("\n", " ").strip()
+    if not message:
+        return type(error).__name__
+    return message[:240]