percolation-inversion-compiler 0.4.1__py3-none-any.whl

percolation_inversion_compiler/__init__.py

@@ -0,0 +1,7 @@
+"""Finite certificate compiler interfaces for ECPT, BIT, TRC, SQOT, and ALT."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.4.1"

percolation_inversion_compiler/adapters/__init__.py

@@ -0,0 +1,39 @@
+"""Optional adapters for scientific OSS dependencies."""
+
+from __future__ import annotations
+
+from percolation_inversion_compiler.adapters.domain import (
+    replay_trc_physical_trace,
+    verify_archive_domain_evidence,
+    verify_ecpt_bridge_reserve,
+    verify_ecpt_domain_abstraction,
+    verify_ecpt_execution_policy,
+    verify_ecpt_generator_limit,
+    verify_ecpt_numerical_envelope,
+    verify_ecpt_proxy_target_contract,
+    verify_ecpt_speculative_channel_repair,
+    verify_ecpt_trace_diagnostic_projection,
+    verify_trc_telemetry_calibration,
+)
+from percolation_inversion_compiler.adapters.graphs import shortest_path_lengths
+from percolation_inversion_compiler.adapters.optimization import solve_linear_release
+from percolation_inversion_compiler.adapters.transport import sinkhorn_transport
+from percolation_inversion_compiler.adapters.units import assert_compatible_units
+
+__all__ = [
+    "assert_compatible_units",
+    "replay_trc_physical_trace",
+    "shortest_path_lengths",
+    "sinkhorn_transport",
+    "solve_linear_release",
+    "verify_archive_domain_evidence",
+    "verify_ecpt_bridge_reserve",
+    "verify_ecpt_domain_abstraction",
+    "verify_ecpt_execution_policy",
+    "verify_ecpt_generator_limit",
+    "verify_ecpt_numerical_envelope",
+    "verify_ecpt_proxy_target_contract",
+    "verify_ecpt_speculative_channel_repair",
+    "verify_ecpt_trace_diagnostic_projection",
+    "verify_trc_telemetry_calibration",
+]

percolation_inversion_compiler/adapters/domain.py

@@ -0,0 +1,338 @@
+"""Deterministic finite domain-adapter checks for production evidence routes."""
+
+from __future__ import annotations
+
+from percolation_inversion_compiler.core.checker import residual_from_reasons
+from percolation_inversion_compiler.core.ledger import CoordinateKind, Ledger
+from percolation_inversion_compiler.core.records import CheckResult
+from percolation_inversion_compiler.core.status import ClaimStatus
+
+
+def _domain_result(name: str, reasons: list[str], residual: Ledger | None = None) -> CheckResult:
+    residual_ledger = residual or Ledger()
+    residual_ledger = residual_ledger.combine(residual_from_reasons(name, reasons))
+    accepted = not reasons
+    return CheckResult(
+        accepted=accepted,
+        status=ClaimStatus.SETTLED if accepted else ClaimStatus.DIAGNOSTIC,
+        finite_checks_passed=accepted,
+        operationally_usable=accepted,
+        settled=accepted,
+        reasons=sorted(set(reasons)),
+        missing_obligations=[] if accepted else [f"{name}:accepted"],
+        residual_ledger=residual_ledger,
+    )
+
+
+def verify_ecpt_numerical_envelope(
+    *,
+    residual: float,
+    residual_bound: float,
+    finite_horizon: int,
+) -> CheckResult:
+    """Check a finite ECPT numerical envelope without asserting limit behavior."""
+
+    reasons: list[str] = []
+    ledger = Ledger()
+    if finite_horizon < 0:
+        reasons.append("finite horizon is negative")
+    if residual < 0 or residual_bound < 0:
+        reasons.append("numerical envelope residuals must be nonnegative")
+    if residual > residual_bound:
+        reasons.append("numerical envelope residual exceeds certified bound")
+        ledger = ledger.add_coordinate(
+            "ecpt:numerical-envelope:gap",
+            residual - residual_bound,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    return _domain_result("ecpt-numerical-envelope", reasons, ledger)
+
+
+def verify_ecpt_generator_limit(
+    *,
+    observed_generation: float,
+    certified_limit: float,
+    residual_allowance: float = 0.0,
+) -> CheckResult:
+    """Check a finite generator-limit certificate."""
+
+    reasons: list[str] = []
+    ledger = Ledger()
+    if certified_limit < 0 or observed_generation < 0 or residual_allowance < 0:
+        reasons.append("generator limit inputs must be nonnegative")
+    gap = observed_generation - certified_limit - residual_allowance
+    if gap > 0:
+        reasons.append("observed generation exceeds certified limit plus residual allowance")
+        ledger = ledger.add_coordinate(
+            "ecpt:generator-limit:excess",
+            gap,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    return _domain_result("ecpt-generator-limit", reasons, ledger)
+
+
+def verify_ecpt_bridge_reserve(
+    bridge_relations: dict[str, str],
+    required_relations: dict[str, str],
+    *,
+    reserve: float,
+    minimum_reserve: float,
+) -> CheckResult:
+    """Check finite cross-theory bridge relations and reserve budget."""
+
+    reasons: list[str] = []
+    ledger = Ledger()
+    if reserve < 0 or minimum_reserve < 0:
+        reasons.append("bridge reserve inputs must be nonnegative")
+    missing = sorted(
+        key for key, target in required_relations.items() if bridge_relations.get(key) != target
+    )
+    if missing:
+        reasons.append("bridge reserve is missing required finite relations")
+    if reserve < minimum_reserve:
+        reasons.append("bridge reserve is below certified minimum")
+        ledger = ledger.add_coordinate(
+            "ecpt:bridge-reserve:gap",
+            minimum_reserve - reserve,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    for key in missing:
+        ledger = ledger.add_coordinate(
+            f"ecpt:bridge-reserve:missing:{key}",
+            1.0,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    return _domain_result("ecpt-bridge-reserve", reasons, ledger)
+
+
+def verify_ecpt_trace_diagnostic_projection(
+    projected_trace_ids: set[str],
+    accepted_trace_ids: set[str],
+    *,
+    residual: float = 0.0,
+) -> CheckResult:
+    """Check finite trace-diagnostic projection containment."""
+
+    reasons: list[str] = []
+    ledger = Ledger()
+    if residual < 0:
+        reasons.append("trace diagnostic residual must be nonnegative")
+    missing = sorted(projected_trace_ids - accepted_trace_ids)
+    if missing:
+        reasons.append("trace diagnostic projection contains unaccepted traces")
+    if residual:
+        ledger = ledger.add_coordinate(
+            "ecpt:trace-diagnostic:residual",
+            residual,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    for trace_id in missing:
+        ledger = ledger.add_coordinate(
+            f"ecpt:trace-diagnostic:missing:{trace_id}",
+            1.0,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    return _domain_result("ecpt-trace-diagnostic", reasons, ledger)
+
+
+def verify_ecpt_domain_abstraction(
+    abstraction_map: dict[str, str],
+    required_targets: set[str],
+    *,
+    refinement_residual: float,
+    residual_bound: float,
+) -> CheckResult:
+    """Check a finite ecology/ontology abstraction envelope."""
+
+    reasons: list[str] = []
+    ledger = Ledger()
+    if refinement_residual < 0 or residual_bound < 0:
+        reasons.append("domain abstraction residuals must be nonnegative")
+    if refinement_residual > residual_bound:
+        reasons.append("domain abstraction refinement residual exceeds bound")
+        ledger = ledger.add_coordinate(
+            "ecpt:domain-abstraction:residual-gap",
+            refinement_residual - residual_bound,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    missing_targets = sorted(required_targets - set(abstraction_map.values()))
+    if missing_targets:
+        reasons.append("domain abstraction misses required target concepts")
+    for target in missing_targets:
+        ledger = ledger.add_coordinate(
+            f"ecpt:domain-abstraction:missing:{target}",
+            1.0,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    return _domain_result("ecpt-domain-abstraction", reasons, ledger)
+
+
+def verify_ecpt_execution_policy(
+    policy_actions: set[str],
+    available_actions: set[str],
+    *,
+    counterfactual_residual: float,
+    residual_bound: float,
+) -> CheckResult:
+    """Check a finite execution-policy/counterfactual envelope."""
+
+    reasons: list[str] = []
+    ledger = Ledger()
+    if counterfactual_residual < 0 or residual_bound < 0:
+        reasons.append("execution-policy residuals must be nonnegative")
+    unavailable = sorted(policy_actions - available_actions)
+    if unavailable:
+        reasons.append("execution policy references unavailable actions")
+    if counterfactual_residual > residual_bound:
+        reasons.append("execution policy counterfactual residual exceeds bound")
+        ledger = ledger.add_coordinate(
+            "ecpt:execution-policy:residual-gap",
+            counterfactual_residual - residual_bound,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    for action in unavailable:
+        ledger = ledger.add_coordinate(
+            f"ecpt:execution-policy:unavailable:{action}",
+            1.0,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    return _domain_result("ecpt-execution-policy", reasons, ledger)
+
+
+def verify_ecpt_proxy_target_contract(
+    proxy_coordinates: dict[str, float],
+    required_coordinates: dict[str, float],
+    *,
+    mismatch_residual: float,
+    residual_bound: float,
+) -> CheckResult:
+    """Check finite proxy-target grounding coordinates."""
+
+    reasons: list[str] = []
+    ledger = Ledger()
+    if mismatch_residual < 0 or residual_bound < 0:
+        reasons.append("proxy-target residuals must be nonnegative")
+    for coordinate, floor in required_coordinates.items():
+        value = proxy_coordinates.get(coordinate, 0.0)
+        if value < floor:
+            reasons.append(f"proxy coordinate {coordinate} is below required floor")
+            ledger = ledger.add_coordinate(
+                f"ecpt:proxy-target:{coordinate}:gap",
+                floor - value,
+                kind=CoordinateKind.RESIDUAL,
+            )
+    if mismatch_residual > residual_bound:
+        reasons.append("proxy-target mismatch residual exceeds bound")
+        ledger = ledger.add_coordinate(
+            "ecpt:proxy-target:mismatch-gap",
+            mismatch_residual - residual_bound,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    return _domain_result("ecpt-proxy-target", reasons, ledger)
+
+
+def verify_ecpt_speculative_channel_repair(
+    channels: set[str],
+    repaired_channels: set[str],
+    required_channels: set[str],
+    *,
+    repair_residual: float,
+    residual_bound: float,
+) -> CheckResult:
+    """Check finite speculative-channel coverage and repair evidence."""
+
+    reasons: list[str] = []
+    ledger = Ledger()
+    if repair_residual < 0 or residual_bound < 0:
+        reasons.append("speculative-channel residuals must be nonnegative")
+    missing = sorted(required_channels - (channels | repaired_channels))
+    if missing:
+        reasons.append("speculative channel repair misses required channels")
+    if repair_residual > residual_bound:
+        reasons.append("speculative channel repair residual exceeds bound")
+        ledger = ledger.add_coordinate(
+            "ecpt:speculative-channel:residual-gap",
+            repair_residual - residual_bound,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    for channel in missing:
+        ledger = ledger.add_coordinate(
+            f"ecpt:speculative-channel:missing:{channel}",
+            1.0,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    return _domain_result("ecpt-speculative-channel", reasons, ledger)
+
+
+def verify_trc_telemetry_calibration(
+    samples: list[float],
+    references: list[float],
+    *,
+    tolerance: float,
+) -> CheckResult:
+    """Check bounded absolute calibration error over finite telemetry samples."""
+
+    reasons: list[str] = []
+    ledger = Ledger()
+    if len(samples) != len(references):
+        reasons.append("telemetry samples and references must have equal length")
+    if not samples:
+        reasons.append("telemetry calibration requires at least one sample")
+    if tolerance < 0:
+        reasons.append("telemetry tolerance must be nonnegative")
+    if not reasons:
+        max_error = max(
+            abs(sample - reference) for sample, reference in zip(samples, references, strict=True)
+        )
+        if max_error > tolerance:
+            reasons.append("telemetry calibration error exceeds tolerance")
+            ledger = ledger.add_coordinate(
+                "trc:telemetry-calibration:error-gap",
+                max_error - tolerance,
+                kind=CoordinateKind.RESIDUAL,
+            )
+    return _domain_result("trc-telemetry-calibration", reasons, ledger)
+
+
+def replay_trc_physical_trace(
+    events: list[str],
+    expected_events: list[str],
+    *,
+    allow_prefix: bool = False,
+) -> CheckResult:
+    """Replay a finite physical trace against an expected transition log."""
+
+    reasons: list[str] = []
+    if not expected_events:
+        reasons.append("expected physical trace is empty")
+    if allow_prefix:
+        accepted = expected_events[: len(events)] == events
+    else:
+        accepted = events == expected_events
+    if not accepted:
+        reasons.append("physical trace does not match expected transition log")
+    return _domain_result("trc-physical-trace", reasons)
+
+
+def verify_archive_domain_evidence(
+    record_domains: dict[str, str],
+    allowed_domains: set[str],
+) -> CheckResult:
+    """Check finite archive records against an explicit allowed-domain set."""
+
+    reasons: list[str] = []
+    if not allowed_domains:
+        reasons.append("archive-domain evidence has no allowed domains")
+    unknown = sorted(
+        record_id for record_id, domain in record_domains.items() if domain not in allowed_domains
+    )
+    if unknown:
+        reasons.append("archive records reference domains outside the certified domain set")
+    ledger = Ledger()
+    for record_id in unknown:
+        ledger = ledger.add_coordinate(
+            f"trc:archive-domain:{record_id}",
+            1.0,
+            kind=CoordinateKind.RESIDUAL,
+        )
+    return _domain_result("trc-archive-domain", reasons, ledger)

percolation_inversion_compiler/adapters/graphs.py

@@ -0,0 +1,15 @@
+"""NetworkX-backed graph helpers kept outside the lean core."""
+
+from __future__ import annotations
+
+
+def shortest_path_lengths(edges: list[tuple[str, str]], source: str) -> dict[str, int]:
+    try:
+        import networkx as nx  # type: ignore[import-untyped]
+    except ImportError as exc:  # pragma: no cover - exercised without science extra
+        raise RuntimeError("Install the 'science' extra to use graph adapters.") from exc
+
+    graph = nx.DiGraph()
+    graph.add_edges_from(edges)
+    lengths = nx.single_source_shortest_path_length(graph, source)
+    return {str(node): int(distance) for node, distance in lengths.items()}

percolation_inversion_compiler/adapters/optimization.py

@@ -0,0 +1,25 @@
+"""Finite LP adapter for release-style certificates."""
+
+from __future__ import annotations
+
+
+def solve_linear_release(
+    objective: list[float],
+    lower_bounds: list[float],
+    upper_bounds: list[float],
+) -> float:
+    """Solve a bounded separable linear release objective.
+
+    This intentionally keeps the public adapter simple and deterministic. More
+    complex constrained LPs should be represented as external proof obligations
+    unless a full matrix certificate is supplied.
+    """
+
+    if len(objective) != len(lower_bounds) or len(objective) != len(upper_bounds):
+        raise ValueError("objective and bound vectors must have equal length")
+    value = 0.0
+    for coeff, lower, upper in zip(objective, lower_bounds, upper_bounds, strict=True):
+        if lower > upper:
+            raise ValueError("lower bound exceeds upper bound")
+        value += coeff * (upper if coeff >= 0 else lower)
+    return value

percolation_inversion_compiler/adapters/transport.py

@@ -0,0 +1,19 @@
+"""Optimal-transport adapters."""
+
+from __future__ import annotations
+
+
+def sinkhorn_transport(
+    source: list[float],
+    target: list[float],
+    cost: list[list[float]],
+    *,
+    regularization: float = 1.0,
+) -> list[list[float]]:
+    try:
+        import ot  # type: ignore[import-untyped]
+    except ImportError as exc:  # pragma: no cover - exercised without ot extra
+        raise RuntimeError("Install the 'ot' extra to use transport adapters.") from exc
+
+    plan = ot.sinkhorn(source, target, cost, regularization)
+    return [[float(value) for value in row] for row in plan.tolist()]

percolation_inversion_compiler/adapters/units.py

@@ -0,0 +1,17 @@
+"""Pint-backed unit validation helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def assert_compatible_units(left_unit: str, right_unit: str) -> bool:
+    try:
+        import pint
+    except ImportError as exc:  # pragma: no cover - exercised without science extra
+        raise RuntimeError("Install the 'science' extra to use unit adapters.") from exc
+
+    registry: Any = pint.UnitRegistry()
+    left = registry.Quantity(1.0, left_unit)
+    right = registry.Quantity(1.0, right_unit)
+    return bool(left.check(right.dimensionality))

percolation_inversion_compiler/agent/__init__.py

@@ -0,0 +1,51 @@
+"""Agent-facing shortcuts for safe PIC runtime integration."""
+
+from __future__ import annotations
+
+from percolation_inversion_compiler.agent.algorithms import (
+    agent_feature_readiness,
+    agent_manifest_payload,
+    agent_network_readiness,
+    agent_safety_invariants,
+    build_agent_communication_guide,
+    build_agent_workflow_guide,
+    minimal_runtime_state,
+    minimal_runtime_step_input,
+    recommend_agent_next_actions,
+    run_agent_intake,
+)
+from percolation_inversion_compiler.agent.records import (
+    AgentCommunicationGuide,
+    AgentCommunicationPolicy,
+    AgentCommunicationStep,
+    AgentFeatureReadinessReport,
+    AgentIntakeReport,
+    AgentIntakeRequest,
+    AgentNetworkReadinessReport,
+    AgentNextActionReport,
+    AgentWorkflowGuide,
+    AgentWorkflowStep,
+)
+
+__all__ = [
+    "AgentCommunicationGuide",
+    "AgentCommunicationPolicy",
+    "AgentCommunicationStep",
+    "AgentFeatureReadinessReport",
+    "AgentIntakeReport",
+    "AgentIntakeRequest",
+    "AgentNetworkReadinessReport",
+    "AgentNextActionReport",
+    "AgentWorkflowGuide",
+    "AgentWorkflowStep",
+    "agent_feature_readiness",
+    "agent_manifest_payload",
+    "agent_network_readiness",
+    "agent_safety_invariants",
+    "build_agent_communication_guide",
+    "build_agent_workflow_guide",
+    "minimal_runtime_state",
+    "minimal_runtime_step_input",
+    "recommend_agent_next_actions",
+    "run_agent_intake",
+]