dir-core 0.3.0__tar.gz → 0.4.2__tar.gz

{dir_core-0.3.0 → dir_core-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dir-core
-Version: 0.3.0
+Version: 0.4.2
 Summary: Decision Intelligence Runtime - deterministic Kernel Space for agentic AI
 Author-email: Artur Huk <artur.huk.it@gmail.com>
 License-Expression: Apache-2.0
@@ -33,6 +33,12 @@ Provides-Extra: samples
 Requires-Dist: markdown>=3.5; extra == "samples"
 Requires-Dist: httpx; extra == "samples"
 Requires-Dist: plotly; extra == "samples"
+Requires-Dist: google-genai>=1.0.0; extra == "samples"
+Provides-Extra: studio
+Requires-Dist: fastapi>=0.110; extra == "studio"
+Requires-Dist: uvicorn[standard]>=0.27; extra == "studio"
+Requires-Dist: z3-solver>=4.12; extra == "studio"
+Requires-Dist: python-dotenv>=1.0; extra == "studio"
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-cov>=4; extra == "dev"
@@ -86,19 +92,21 @@ DIR proposes that many of these discussions can be viewed through a common archi
 
 DIR is built on the formal premise that an AI agent cannot be trusted to maintain system integrity probabilistically. Instead, the runtime ensures that the system never enters an **Illegal Decision State**.
 
-A decision is considered execution-safe—and allowed to pass through the runtime—only when five independent dimensions are simultaneously satisfied. We call this the **Legal Decision State (LDS)**:
+<p align="center">
+	<img src="./assets/images/lds-octagon.jpg" alt="Legal Decision State Invariants" width="60%">
+</p>
 
-$$LDS = C \wedge A \wedge I \wedge E \wedge T$$
+A decision is considered execution-safe—and allowed to pass through the runtime—only when five independent dimensions are simultaneously satisfied. We call this the **Legal Decision State (LDS)**:
 
-![Legal Decision State Invariants](./assets/images/lds-octagon.png)
+$$LDS = A \wedge C \wedge T \wedge I \wedge E$$
 
-If any of these components is false ($\neg C \vee \neg A \vee \neg I \vee \neg E \vee \neg T$), the decision is structurally illegal and must be aborted. Every component in the DIR ecosystem exists exclusively to protect one of these invariants:
+If any of these components is false ($\neg A \vee \neg C \vee \neg T \vee \neg I \vee \neg E$), the decision is structurally illegal and must be aborted. Every component in the DIR ecosystem exists exclusively to protect one of these invariants:
 
-- **Context (C):** Protected by the **Context Store** & **Context-as-Code (CaC)**. Ensures the agent is not acting on stale, hallucinated, or mission-drifted data.
 - **Authority (A):** Protected by **Responsibility-Oriented Agents (ROA)**. Ensures the agent's proposed action does not exceed its explicitly registered contractual limits.
+- **Context (C):** Protected by the **Context Store** & **Context-as-Code (CaC)**. Ensures the agent is not acting on stale, hallucinated, or mission-drifted data.
+- **Time (T):** Protected by **JIT State Verification** & **Drift Envelopes**. Prevents Time-of-Check to Time-of-Use (TOCTOU) races by ensuring reality hasn't shifted between LLM reasoning and API execution.
 - **Intent (I):** Protected by **SDS Grammars** & **DIM Schema Validation**. Ensures the action is syntactically valid and structurally executable.
 - **Evidence (E):** Protected by the **Evidence Governance Layer**. Detects "Compliant Lies" by ensuring the action is backed by deterministically reproducible reasoning.
-- **Time (T):** Protected by **JIT State Verification** & **Drift Envelopes**. Prevents Time-of-Check to Time-of-Use (TOCTOU) races by ensuring reality hasn't shifted between LLM reasoning and API execution.
 
 *The Decision Integrity Module (DIM) is the deterministic gatekeeper that mathematically enforces this equation before any side effect occurs.*
 

{dir_core-0.3.0 → dir_core-0.4.2}/README.md

@@ -44,19 +44,21 @@ DIR proposes that many of these discussions can be viewed through a common archi
 
 DIR is built on the formal premise that an AI agent cannot be trusted to maintain system integrity probabilistically. Instead, the runtime ensures that the system never enters an **Illegal Decision State**.
 
-A decision is considered execution-safe—and allowed to pass through the runtime—only when five independent dimensions are simultaneously satisfied. We call this the **Legal Decision State (LDS)**:
+<p align="center">
+	<img src="./assets/images/lds-octagon.jpg" alt="Legal Decision State Invariants" width="60%">
+</p>
 
-$$LDS = C \wedge A \wedge I \wedge E \wedge T$$
+A decision is considered execution-safe—and allowed to pass through the runtime—only when five independent dimensions are simultaneously satisfied. We call this the **Legal Decision State (LDS)**:
 
-![Legal Decision State Invariants](./assets/images/lds-octagon.png)
+$$LDS = A \wedge C \wedge T \wedge I \wedge E$$
 
-If any of these components is false ($\neg C \vee \neg A \vee \neg I \vee \neg E \vee \neg T$), the decision is structurally illegal and must be aborted. Every component in the DIR ecosystem exists exclusively to protect one of these invariants:
+If any of these components is false ($\neg A \vee \neg C \vee \neg T \vee \neg I \vee \neg E$), the decision is structurally illegal and must be aborted. Every component in the DIR ecosystem exists exclusively to protect one of these invariants:
 
-- **Context (C):** Protected by the **Context Store** & **Context-as-Code (CaC)**. Ensures the agent is not acting on stale, hallucinated, or mission-drifted data.
 - **Authority (A):** Protected by **Responsibility-Oriented Agents (ROA)**. Ensures the agent's proposed action does not exceed its explicitly registered contractual limits.
+- **Context (C):** Protected by the **Context Store** & **Context-as-Code (CaC)**. Ensures the agent is not acting on stale, hallucinated, or mission-drifted data.
+- **Time (T):** Protected by **JIT State Verification** & **Drift Envelopes**. Prevents Time-of-Check to Time-of-Use (TOCTOU) races by ensuring reality hasn't shifted between LLM reasoning and API execution.
 - **Intent (I):** Protected by **SDS Grammars** & **DIM Schema Validation**. Ensures the action is syntactically valid and structurally executable.
 - **Evidence (E):** Protected by the **Evidence Governance Layer**. Detects "Compliant Lies" by ensuring the action is backed by deterministically reproducible reasoning.
-- **Time (T):** Protected by **JIT State Verification** & **Drift Envelopes**. Prevents Time-of-Check to Time-of-Use (TOCTOU) races by ensuring reality hasn't shifted between LLM reasoning and API execution.
 
 *The Decision Integrity Module (DIM) is the deterministic gatekeeper that mathematically enforces this equation before any side effect occurs.*
 

{dir_core-0.3.0 → dir_core-0.4.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 # dir-core keeps pip install name and import path aligned (frictionless adoption).
 name = "dir-core"
-version = "0.3.0"
+version = "0.4.2"
 description = "Decision Intelligence Runtime - deterministic Kernel Space for agentic AI"
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,7 +35,8 @@ postgres = ["psycopg[binary]>=3.1"]
 asyncpg = ["asyncpg>=0.29"]
 # Optional: Boxed Intelligence pattern (wrappers)
 frameworks = ["langchain-core", "crewai"]
-samples = ["markdown>=3.5", "httpx", "plotly"]
+samples = ["markdown>=3.5", "httpx", "plotly", "google-genai>=1.0.0"]
+studio = ["fastapi>=0.110", "uvicorn[standard]>=0.27", "z3-solver>=4.12", "python-dotenv>=1.0"]
 dev = [
     "pytest>=7",
     "pytest-cov>=4",

{dir_core-0.3.0 → dir_core-0.4.2}/src/dir_core/__init__.py

@@ -21,7 +21,7 @@ Custom storage backend example::
     registry = AgentRegistry(storage=MyPostgresStorage())
 """
 
-from .agent_registry import AgentRegistry, HandshakeResult
+from .agent_registry import AgentRegistry, AmendmentResult, HandshakeResult
 from .arbitration import DEFAULT_PRIORITY_MATRIX, select_winner
 from .dim import validate_proposal
 from .data_types import (
@@ -80,6 +80,10 @@ from .models import (
     PolicyProposal,
     ProofCarryingIntent,
     CompensationAction,
+    ContractReleaseRef,
+    RuntimeContractProjection,
+    InvariantSpec,
+    ContractParameterAmendment,
     ResponsibilityContract,
     SelfCheckResult,
 )
@@ -90,6 +94,9 @@ from .pci import (
     hash_content,
     proposal_params_for_hash,
 )
+from .contract_projection import project_contract, responsibility_contract_from_projection
+from .invariants import evaluate_invariants
+from .amendments import validate_amendment_patch
 from .wakeup import (
     WakeupPredicate,
     is_relevant_instrument,
@@ -214,6 +221,15 @@ __all__ = [
     "verify_drift",
     # Core models
     "ResponsibilityContract",
+    "ContractReleaseRef",
+    "RuntimeContractProjection",
+    "InvariantSpec",
+    "ContractParameterAmendment",
+    "AmendmentResult",
+    "project_contract",
+    "responsibility_contract_from_projection",
+    "evaluate_invariants",
+    "validate_amendment_patch",
     "PolicyProposal",
     "ExecutionIntent",
     # ROA Lifecycle models

{dir_core-0.3.0 → dir_core-0.4.2}/src/dir_core/agent_registry.py

@@ -14,6 +14,9 @@ from dataclasses import dataclass
 from typing import Any, Dict, List, Optional
 
 from .data_types import AgentRegistryStatus, HandshakeRejectionReason
+from .amendments import validate_amendment_patch, resolve_expires_at
+from .contract_projection import project_contract
+from .models import ContractParameterAmendment, RuntimeContractProjection
 from .storage.base import AgentRegistryStorage
 from .storage.sqlite import SqliteAgentRegistryStorage
 
@@ -31,6 +34,15 @@ class HandshakeResult:
     reason: Optional[str] = None
 
 
+@dataclass
+class AmendmentResult:
+    """Result of applying a human-gated parameter amendment."""
+
+    accepted: bool
+    reason: Optional[str] = None
+    projection: Optional[RuntimeContractProjection] = None
+
+
 def _parse_version(v: str) -> Optional[tuple]:
     """Parse semver string to (major, minor, patch)."""
     m = SEMVER_RE.match(v.strip())
@@ -121,6 +133,22 @@ class AgentRegistry:
         logger.info("Handshake: agent_id=%s ver=%s accepted", agent_id, agent_version)
         return HandshakeResult(accepted=True, session_token=token)
 
+    def register_projection(
+        self,
+        projection: RuntimeContractProjection,
+        agent_version: str,
+        priority: int = 0,
+    ) -> HandshakeResult:
+        """Register an approved RuntimeContractProjection explicitly."""
+        if projection.agent_id == "":
+            return HandshakeResult(accepted=False, reason="MISSING_AGENT_ID")
+        return self.handshake(
+            projection.agent_id,
+            projection.model_dump(mode="json"),
+            agent_version,
+            priority=priority,
+        )
+
     def get_schema(
         self, agent_id: str, schema_kind: Optional[str] = None
     ) -> Optional[dict]:
@@ -164,6 +192,69 @@ class AgentRegistry:
         rec = self._storage.get_agent(agent_id)
         return rec["contract"] if rec else None
 
+    def get_agent_projection(
+        self, agent_id: str
+    ) -> Optional[RuntimeContractProjection]:
+        """Retrieve the registered contract as an execution projection."""
+        contract = self.get_agent_contract(agent_id)
+        return project_contract(contract) if contract is not None else None
+
+    def apply_parameter_amendment(
+        self,
+        amendment: ContractParameterAmendment,
+    ) -> AmendmentResult:
+        """Apply a human-gated scalar patch to a runtime-amendable invariant."""
+        projection = self.get_agent_projection(amendment.agent_id)
+        if projection is None:
+            return AmendmentResult(accepted=False, reason="AGENT_NOT_FOUND")
+
+        target = next(
+            (spec for spec in projection.invariants if spec.id == amendment.invariant_id),
+            None,
+        )
+        if target is None:
+            return AmendmentResult(accepted=False, reason="INVARIANT_NOT_FOUND")
+
+        reject_reason = validate_amendment_patch(target, amendment.patch)
+        if reject_reason is not None:
+            return AmendmentResult(accepted=False, reason=reject_reason)
+
+        stored = dict(self.get_agent_contract(amendment.agent_id) or {})
+        if not stored.get("invariants"):
+            stored = projection.model_dump(mode="json")
+
+        amendments = list(stored.get("parameter_amendments") or [])
+        payload = amendment.model_dump(mode="json")
+        payload["expires_at"] = (
+            resolve_expires_at(amendment, target).isoformat()
+            if resolve_expires_at(amendment, target) is not None
+            else None
+        )
+        amendments.append(payload)
+        stored["parameter_amendments"] = amendments
+
+        rec = self._storage.get_agent(amendment.agent_id)
+        agent_version = rec.get("agent_version") if rec else "1.0.0"
+        if not agent_version:
+            agent_version = "1.0.0"
+
+        self._storage.upsert_agent(
+            agent_id=amendment.agent_id,
+            contract_json=json.dumps(stored),
+            priority=rec["priority"] if rec else 0,
+            status=AgentRegistryStatus.ACTIVE,
+            agent_version=agent_version,
+            session_token=rec.get("session_token") if rec else None,
+        )
+        updated = self.get_agent_projection(amendment.agent_id)
+        logger.info(
+            "Parameter amendment: agent_id=%s invariant_id=%s actor=%s",
+            amendment.agent_id,
+            amendment.invariant_id,
+            amendment.actor_id,
+        )
+        return AmendmentResult(accepted=True, projection=updated)
+
     def get_agent_manifest(self, agent_id: str) -> Optional[Dict[str, Any]]:
         """Retrieve agent capability contract. Deprecated: use get_agent_contract."""
         return self.get_agent_contract(agent_id)

dir_core-0.4.2/src/dir_core/amendments.py

@@ -0,0 +1,137 @@
+"""Apply human-gated parameter amendments to runtime contract projections."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from .models import (
+    ContractParameterAmendment,
+    InvariantSpec,
+    RuntimeContractProjection,
+)
+
+ALLOWED_PATCH_KEYS = frozenset({"min", "max", "allowed", "drift_envelope_pct"})
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def apply_amendment_patch(
+    invariant: InvariantSpec,
+    patch: dict[str, Any],
+) -> InvariantSpec:
+    """Return a copy of invariant with scalar patch applied."""
+    data = invariant.model_dump()
+    for key, value in patch.items():
+        data[key] = value
+    return InvariantSpec.model_validate(data)
+
+
+def validate_amendment_patch(
+    invariant: InvariantSpec,
+    patch: dict[str, Any],
+    *,
+    now: datetime | None = None,
+) -> str | None:
+    """Validate amendment patch against runtime_amendable rules and envelope."""
+    now = now or _utcnow()
+    if not invariant.runtime_amendable:
+        return "INVARIANT_NOT_AMENDABLE"
+
+    if not patch:
+        return "EMPTY_PATCH"
+
+    invalid_keys = set(patch) - ALLOWED_PATCH_KEYS
+    if invalid_keys:
+        return f"DISALLOWED_PATCH_KEYS: {sorted(invalid_keys)}"
+
+    if "max" in patch and patch["max"] is not None:
+        new_max = float(patch["max"])
+        if invariant.max_ceiling is not None and new_max > float(invariant.max_ceiling):
+            return "PATCH_EXCEEDS_MAX_CEILING"
+        if invariant.min_floor is not None and new_max < float(invariant.min_floor):
+            return "PATCH_BELOW_MIN_FLOOR"
+
+    if "min" in patch and patch["min"] is not None:
+        new_min = float(patch["min"])
+        if invariant.min_floor is not None and new_min < float(invariant.min_floor):
+            return "PATCH_BELOW_MIN_FLOOR"
+        if invariant.max_ceiling is not None and new_min > float(invariant.max_ceiling):
+            return "PATCH_EXCEEDS_MAX_CEILING"
+
+    if "allowed" in patch:
+        new_allowed = list(patch["allowed"])
+        if not isinstance(patch["allowed"], list):
+            return "ALLOWED_PATCH_MUST_BE_LIST"
+        signed_allowed = set(invariant.allowed)
+        if signed_allowed and not set(new_allowed).issubset(signed_allowed):
+            return "ALLOWED_PATCH_EXPANSION_FORBIDDEN"
+        if not signed_allowed and invariant.type == "set":
+            return "ALLOWED_PATCH_REQUIRES_SIGNED_BASE"
+
+    if "drift_envelope_pct" in patch and patch["drift_envelope_pct"] is not None:
+        new_drift = float(patch["drift_envelope_pct"])
+        if new_drift < 0:
+            return "DRIFT_ENVELOPE_NEGATIVE"
+
+    if invariant.amend_ttl_seconds is not None and invariant.amend_ttl_seconds <= 0:
+        return "INVALID_AMEND_TTL"
+
+    return None
+
+
+def resolve_expires_at(
+    amendment: ContractParameterAmendment,
+    invariant: InvariantSpec,
+) -> datetime | None:
+    if amendment.expires_at is not None:
+        return amendment.expires_at
+    if invariant.amend_ttl_seconds:
+        return amendment.created_at + timedelta(seconds=int(invariant.amend_ttl_seconds))
+    return None
+
+
+def effective_invariants(
+    projection: RuntimeContractProjection,
+    *,
+    now: datetime | None = None,
+) -> list[InvariantSpec]:
+    """Merge base invariants with active parameter amendments."""
+    now = now or _utcnow()
+    by_id = {spec.id: spec for spec in projection.invariants}
+
+    for amendment in projection.parameter_amendments:
+        expires_at = resolve_expires_at(amendment, by_id.get(amendment.invariant_id, InvariantSpec(
+            id=amendment.invariant_id,
+            type="range",
+            field="policy_kind",
+        )))
+        if expires_at is not None and now >= expires_at:
+            continue
+        base = by_id.get(amendment.invariant_id)
+        if base is None:
+            continue
+        by_id[amendment.invariant_id] = apply_amendment_patch(base, amendment.patch)
+
+    return list(by_id.values())
+
+
+def projection_with_effective_invariants(
+    projection: RuntimeContractProjection,
+    *,
+    now: datetime | None = None,
+) -> RuntimeContractProjection:
+    """Return projection copy whose invariants reflect active amendments."""
+    effective = effective_invariants(projection, now=now)
+    data = projection.model_dump(mode="python")
+    data["invariants"] = effective
+    data["transaction_limits"] = _limits_from_invariants(effective)
+    return RuntimeContractProjection.model_validate(data)
+
+
+def _limits_from_invariants(invariants: list[InvariantSpec]) -> dict[str, dict[str, Any]]:
+    from .invariant_compile import invariants_to_transaction_limits
+
+    return invariants_to_transaction_limits(invariants)

dir_core-0.4.2/src/dir_core/contract_projection.py

@@ -0,0 +1,238 @@
+"""Normalize canonical and legacy contracts into a Runtime projection."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .invariant_compile import compile_authority_invariants, invariants_to_transaction_limits
+from .models import (
+    ContractParameterAmendment,
+    ContractReleaseRef,
+    InvariantSpec,
+    ResponsibilityContract,
+    RuntimeContractProjection,
+)
+
+
+def _as_limit(value: Any) -> dict[str, Any] | None:
+    """Convert a legacy numeric limit to the projection's typed shape."""
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return {"value": float(value)}
+    if isinstance(value, Mapping) and "value" in value:
+        return dict(value)
+    return None
+
+
+def _is_projection_dump(data: Mapping[str, Any]) -> bool:
+    """Detect serialized RuntimeContractProjection payloads."""
+    if "release" in data and ("invariants" in data or "transaction_limits" in data):
+        return True
+    if "agent_id" in data and "invariants" in data and "allowed_policy_types" in data:
+        return True
+    return False
+
+
+def _build_projection_from_contract_mapping(data: Mapping[str, Any]) -> RuntimeContractProjection:
+    metadata = dict(data.get("metadata") or {})
+    subject = dict(data.get("subject") or {})
+    authority = dict(data.get("authority") or {})
+    responsibility = dict(data.get("responsibility") or {})
+    governance = dict(data.get("governance") or {})
+
+    legacy_permissions = dict(data.get("permissions") or {})
+    if not authority and legacy_permissions:
+        authority = legacy_permissions
+    if not authority and (
+        "allowed_policy_types" in data or "authorized_instruments" in data
+    ):
+        authority = {
+            key: value
+            for key, value in data.items()
+            if key in {"allowed_policy_types", "authorized_instruments"}
+            or key.startswith("max_")
+        }
+
+    release = ContractReleaseRef(
+        contract_id=str(metadata.get("contract_id", data.get("contract_id", "legacy"))),
+        contract_version=str(metadata.get("version", data.get("version", "0.0.0"))),
+        api_version=str(metadata.get("api_version", data.get("api_version", "legacy"))),
+        contract_hash=str(metadata.get("contract_hash", data.get("contract_hash", ""))),
+    )
+
+    invariants = compile_authority_invariants(data)
+    transaction_limits = invariants_to_transaction_limits(invariants)
+
+    legacy_limits: dict[str, dict[str, Any]] = {}
+    source_limits = dict(authority.get("limits") or {})
+    if not source_limits:
+        source_limits = {
+            key: value
+            for key, value in authority.items()
+            if key
+            not in {
+                "allowed_policy_types",
+                "authorized_instruments",
+                "resource_scope",
+                "invariants",
+            }
+        }
+    for key, value in source_limits.items():
+        typed_limit = _as_limit(value)
+        if typed_limit is not None:
+            legacy_limits[str(key)] = typed_limit
+    for key, value in legacy_limits.items():
+        transaction_limits.setdefault(key, value)
+
+    evidence = dict(responsibility.get("evidence") or {})
+    if not evidence and "evidence_level" in responsibility:
+        evidence["level"] = responsibility["evidence_level"]
+
+    escalation = dict(responsibility.get("escalation") or {})
+    if not escalation:
+        if "escalation" in responsibility:
+            escalation["mode"] = responsibility["escalation"]
+        if "escalate_on_uncertainty" in responsibility:
+            escalation["confidence_below"] = responsibility["escalate_on_uncertainty"]
+
+    mission_value = data.get("mission", "")
+    if isinstance(mission_value, Mapping):
+        mission_value = mission_value.get("statement", "")
+
+    aggregate_raw = governance.get("aggregate_policies") or []
+    aggregate_policies = list(aggregate_raw) if isinstance(aggregate_raw, list) else []
+
+    return RuntimeContractProjection(
+        release=release,
+        agent_id=str(subject.get("agent_id", data.get("agent_id", ""))),
+        role=subject.get("role", data.get("role", "EXECUTOR")),
+        parent_agent_id=subject.get("parent_agent_id", data.get("parent_agent_id")),
+        mission=str(mission_value),
+        allowed_policy_types=list(
+            authority.get("allowed_policy_types")
+            or legacy_permissions.get("allowed_policy_types")
+            or []
+        ),
+        resource_scope=dict(authority.get("resource_scope") or {}),
+        transaction_limits=transaction_limits,
+        execution_conditions=dict(data.get("execution_conditions") or {}),
+        evidence_requirements=evidence,
+        escalation_policy=escalation,
+        aggregate_policies=aggregate_policies,
+        invariants=invariants,
+        parameter_amendments=[],
+    )
+
+
+def ensure_projection_invariants(projection: RuntimeContractProjection) -> RuntimeContractProjection:
+    """Backfill invariant IR when only legacy projection fields were stored."""
+    if projection.invariants:
+        return projection
+    if (
+        not projection.allowed_policy_types
+        and not projection.transaction_limits
+        and not projection.resource_scope.get("instruments")
+        and not projection.execution_conditions
+    ):
+        return projection
+
+    rebuilt = _build_projection_from_contract_mapping(
+        {
+            "metadata": projection.release.model_dump(mode="json"),
+            "subject": {"agent_id": projection.agent_id, "role": projection.role},
+            "mission": {"statement": projection.mission},
+            "authority": {
+                "allowed_policy_types": projection.allowed_policy_types,
+                "resource_scope": projection.resource_scope,
+                "limits": projection.transaction_limits,
+            },
+            "execution_conditions": projection.execution_conditions,
+            "responsibility": {"escalation": projection.escalation_policy},
+            "governance": {"aggregate_policies": projection.aggregate_policies},
+        }
+    )
+    if not rebuilt.invariants:
+        return projection
+    data = projection.model_dump(mode="python")
+    data["invariants"] = rebuilt.invariants
+    data["transaction_limits"] = rebuilt.transaction_limits
+    return RuntimeContractProjection.model_validate(data)
+
+
+def _parse_projection_dump(data: Mapping[str, Any]) -> RuntimeContractProjection:
+    payload = dict(data)
+    invariants_raw = payload.get("invariants") or []
+    payload["invariants"] = [
+        spec if isinstance(spec, InvariantSpec) else InvariantSpec.model_validate(spec)
+        for spec in invariants_raw
+    ]
+    amendments_raw = payload.get("parameter_amendments") or []
+    payload["parameter_amendments"] = [
+        amendment
+        if isinstance(amendment, ContractParameterAmendment)
+        else ContractParameterAmendment.model_validate(amendment)
+        for amendment in amendments_raw
+    ]
+    if not payload.get("transaction_limits") and payload.get("invariants"):
+        payload["transaction_limits"] = invariants_to_transaction_limits(payload["invariants"])
+    aggregate_raw = payload.get("aggregate_policies")
+    if aggregate_raw is None or isinstance(aggregate_raw, dict):
+        payload["aggregate_policies"] = []
+    projection = RuntimeContractProjection.model_validate(payload)
+    return ensure_projection_invariants(projection)
+
+
+def project_contract(contract: Mapping[str, Any]) -> RuntimeContractProjection:
+    """Create the execution-facing projection from a contract mapping."""
+    data = dict(contract)
+    if _is_projection_dump(data):
+        return _parse_projection_dump(data)
+    return ensure_projection_invariants(_build_projection_from_contract_mapping(data))
+
+
+def _limit_value(projection: RuntimeContractProjection, key: str) -> float | None:
+    raw = projection.transaction_limits.get(key)
+    if not isinstance(raw, Mapping):
+        return None
+    value = raw.get("value")
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value)
+
+
+def responsibility_contract_from_projection(
+    projection: RuntimeContractProjection,
+) -> ResponsibilityContract:
+    """Derive the flat agent-facing ``ResponsibilityContract`` from a projection.
+
+    ``max_drawdown_limit`` is a fraction (0.04 = 4%); ``max_drawdown_limit_pct`` is in percent points.
+    """
+    fields: dict[str, Any] = {
+        "agent_id": projection.agent_id,
+        "role": projection.role,
+        "mission": projection.mission,
+        "authorized_instruments": list(
+            projection.resource_scope.get("instruments")
+            or projection.resource_scope.get("categories")
+            or []
+        ),
+        "allowed_policy_types": list(projection.allowed_policy_types),
+        "parent_agent_id": projection.parent_agent_id,
+    }
+
+    confidence_below = projection.escalation_policy.get("confidence_below")
+    if confidence_below is not None:
+        fields["escalate_on_uncertainty"] = float(confidence_below)
+
+    wake_up = projection.execution_conditions.get("wake_up_threshold_pct")
+    if wake_up is not None:
+        fields["wake_up_threshold_pct"] = float(wake_up)
+
+    drawdown = _limit_value(projection, "max_drawdown_limit")
+    if drawdown is None:
+        drawdown_pct = _limit_value(projection, "max_drawdown_limit_pct")
+        drawdown = drawdown_pct / 100.0 if drawdown_pct is not None else None
+    if drawdown is not None:
+        fields["max_drawdown_limit"] = drawdown
+
+    return ResponsibilityContract(**fields)

{dir_core-0.3.0 → dir_core-0.4.2}/src/dir_core/data_types.py

@@ -17,6 +17,12 @@ class DimReasonCode(StrEnum):
 
     REASONING_EXHAUSTION = "REASONING_EXHAUSTION"
     TTL_EXPIRED = "TTL_EXPIRED"
+    AGENT_SUSPENDED = "AGENT_SUSPENDED"
+    AGENT_RETIRED = "AGENT_RETIRED"
+    AGENT_DEGRADED = "AGENT_DEGRADED"
+    CONTRACT_LIMIT_EXCEEDED = "CONTRACT_LIMIT_EXCEEDED"
+    CONTRACT_PARAMETER_MISSING = "CONTRACT_PARAMETER_MISSING"
+    INVARIANT_VIOLATION = "INVARIANT_VIOLATION"
     VALIDATION_PASSED = "VALIDATION_PASSED"
 
 
@@ -88,6 +94,10 @@ class AgentRegistryStatus(StrEnum):
     """Agent row status in registry storage."""
 
     ACTIVE = "ACTIVE"
+    SUSPENDED = "SUSPENDED"
+    DEGRADED = "DEGRADED"
+    ESCALATION_ONLY = "ESCALATION_ONLY"
+    RETIRED = "RETIRED"
 
 
 class HandshakeRejectionReason(StrEnum):