engineering-argument-language 3.2.3__py3-none-any.whl

eal/reasoning/strategy.py

@@ -0,0 +1,18 @@
+"""An immutable selection of one stateless built-in implementation.
+
+Computational strategies return an assessment envelope. The structured strategy
+returns authored-support details; its availability depends on evidence/premises
+and is assessed by the common facade. Each registered schema defines the exact
+contract. Keeping callbacks as module-level functions preserves code identity
+checks and avoids stateful instances crossing the method registration boundary.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class BuiltinStrategy:
+    mode: str
+    compute: Callable[[dict], dict]

eal/reasoning/structured.py

@@ -0,0 +1,11 @@
+"""Mark authored support without asserting a mechanical proof."""
+from __future__ import annotations
+
+from .strategy import BuiltinStrategy
+
+
+def _structured_marker(payload):
+    return {'authored': True, 'mechanically_proved': False}
+
+
+STRATEGY = BuiltinStrategy("structured", _structured_marker)

eal/reasoning/temporal.py

@@ -0,0 +1,47 @@
+"""Check a property and sampling coverage over a bounded recorded trace."""
+from __future__ import annotations
+
+import operator
+
+from .strategy import BuiltinStrategy
+from .validation import _list, _number, _object, _result
+
+
+def _temporal(value):
+    _object(value, ("start", "end", "max_gap", "events", "property", "semantics"), "trace")
+    if value["semantics"] != "sampled":
+        raise ValueError("Temporal mode supports only explicitly sampled semantics")
+    start, end, max_gap = [_number(value[key], key) for key in ("start", "end", "max_gap")]
+    if start > end or max_gap <= 0:
+        raise ValueError("Trace requires start <= end and max_gap > 0")
+    _object(value["property"], ("operator", "value"), "trace property")
+    comparisons = {"lt": operator.lt, "le": operator.le, "eq": operator.eq,
+                   "ne": operator.ne, "ge": operator.ge, "gt": operator.gt}
+    op = value["property"]["operator"]
+    if not isinstance(op, str) or op not in comparisons:
+        raise ValueError("Trace property operator must be lt/le/eq/ne/ge/gt")
+    threshold = _number(value["property"]["value"], "property value")
+    events = _list(value["events"], "events")
+    times, failures = [], []
+    for event in events:
+        _object(event, ("time", "value"), "trace event")
+        time = _number(event["time"], "event time")
+        observation = _number(event["value"], "event value")
+        if not start <= time <= end or times and time <= times[-1]:
+            raise ValueError("Events must be strictly time-ordered and within the declared interval")
+        times.append(time)
+        if not comparisons[op](observation, threshold):
+            failures.append(time)
+    largest_gap = max((b - a for a, b in zip(times, times[1:])), default=0.0)
+    coverage = times[0] == start and times[-1] == end and largest_gap <= max_gap
+    holds = not failures
+    return _result(coverage,
+                   "The sampled property holds throughout the complete declared sampling contract" if coverage and holds
+                   else "The sampling contract has a gap or missing endpoint" if not coverage
+                   else "The sampled trace contains a property violation",
+                   holds=holds, coverage=coverage, sample_size=len(events), largest_gap=largest_gap,
+                   violation_count=len(failures), violation_times=failures,
+                   semantics="sampled", continuous_truth_established=False)
+
+
+STRATEGY = BuiltinStrategy("temporal", _temporal)

eal/reasoning/validation.py

@@ -0,0 +1,90 @@
+"""Bound and validate JSON evidence used by built-in calculations."""
+from __future__ import annotations
+
+import re
+
+MAX_ITEMS = 10_000
+_IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_]{0,63}\Z")
+
+
+def _object(value, fields, label):
+    if not isinstance(value, dict) or set(value) != set(fields):
+        raise ValueError(f"{label} requires exactly these fields: {', '.join(fields)}")
+    return value
+
+
+def _list(value, label, minimum=1, maximum=MAX_ITEMS):
+    if not isinstance(value, list) or not minimum <= len(value) <= maximum:
+        raise ValueError(f"{label} must be a list with {minimum}..{maximum} entries")
+    return value
+
+
+def _number(value, label):
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{label} must be a finite number")
+    if not -1e100 <= value <= 1e100:
+        raise ValueError(f"{label} must be finite and within [-1e100, 1e100]")
+    return value
+
+
+def _integer(value, label, minimum=0, maximum=1_000_000_000):
+    if type(value) is not int or not minimum <= value <= maximum:
+        raise ValueError(f"{label} must be an integer in [{minimum}, {maximum}]")
+    return value
+
+
+def _name(value, label):
+    if not isinstance(value, str) or not _IDENTIFIER.fullmatch(value):
+        raise ValueError(f"{label} must be an identifier of at most 64 characters")
+    return value
+
+
+def _text(value, label):
+    if not isinstance(value, str) or not value.strip() or len(value) > 4096:
+        raise ValueError(f"{label} must contain 1..4096 characters and be nonblank")
+    return value
+
+
+def _probability(value, label):
+    value = _number(value, label)
+    if not 0 <= value <= 1:
+        raise ValueError(f"{label} must be in [0, 1]")
+    return value
+
+
+def _result(ok, reason, **details):
+    return {"status": "supported" if ok else "unsupported",
+            "reasons": [reason], "details": details}
+
+
+def _check_json(value):
+    """Bound every input before mode-specific traversal, including cycles."""
+    pending = [(value, 0)]
+    count = 0
+    while pending:
+        item, depth = pending.pop()
+        count += 1
+        if count > 100_000 or depth > 64:
+            raise ValueError("Evidence exceeds JSON node or depth limits")
+        if item is None or isinstance(item, bool):
+            continue
+        if isinstance(item, str):
+            if len(item) > 4096:
+                raise ValueError("Evidence strings are limited to 4096 characters")
+            item.encode("utf-8")
+        elif isinstance(item, (int, float)):
+            _number(item, "Evidence number")
+        elif isinstance(item, dict):
+            if len(item) > MAX_ITEMS:
+                raise ValueError("Evidence object exceeds member limit")
+            for key, child in item.items():
+                if not isinstance(key, str) or len(key) > 4096:
+                    raise ValueError("Evidence object keys must be bounded strings")
+                key.encode("utf-8")
+                pending.append((child, depth + 1))
+        elif isinstance(item, list):
+            if len(item) > MAX_ITEMS:
+                raise ValueError("Evidence list exceeds entry limit")
+            pending.extend((child, depth + 1) for child in item)
+        else:
+            raise ValueError("Evidence must contain only JSON values")

eal/registered_assessment.py

@@ -0,0 +1,181 @@
+"""One-call assessment of a developer-registered EAL claim.
+
+The catalogue selects trusted source and claims. A caller names an entry and
+claim; the host plans acquisition, reuses only eligible observations, collects
+the remainder and returns a bounded packet. The stored assessment and
+collection retain the full explanation and observations by ID.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any, Literal
+
+from .catalogue import WorkspaceKnowledgeCatalogue
+from .evaluator import assess_environment, assess_evidence_record, canonical_digest
+from .observation_reuse import ObservationRebinder
+from .parser import parse
+from .runtime import MAX_COLLECTION_BYTES, MAX_COLLECTION_EVIDENCE, ReasoningService
+from .semantics import parse_time
+from .store import utc_now
+
+
+class RegisteredAssessmentHost:
+    """Execute one registered claim without requiring model tool orchestration."""
+
+    def __init__(self, service: ReasoningService, catalogue: WorkspaceKnowledgeCatalogue):
+        if catalogue.service is not service:
+            raise ValueError("Catalogue and assessment host must use the same service")
+        self.service = service
+        self.catalogue = catalogue
+        self.rebinder = ObservationRebinder(service.store)
+
+    def _candidate(self, program: Any, context: dict, name: str, *, instant: datetime,
+                   binding_digest: str | None, execution_digest: str | None) -> dict | None:
+        if binding_digest is None:
+            return None
+        environment = program.environments[program.evidence[name].environment]
+        if assess_environment(environment, context)["status"] != "matched":
+            return None
+        for original in self.rebinder.candidates(
+            program, context, name, current_binding_digest=binding_digest,
+            current_execution_digest=execution_digest,
+        ):
+            try:
+                derived = self.rebinder.prepare_record(
+                    program, context, name, original,
+                    current_binding_digest=binding_digest,
+                    current_execution_digest=execution_digest,
+                )
+            except (ValueError, TypeError, OverflowError):
+                continue
+            verdict = assess_evidence_record(
+                program, name, derived, instant=instant, context=context,
+                environment_matched=True, expected_tool_binding_digest=binding_digest,
+                check_current_binding=True,
+            )
+            # A comparable negative measurement is reusable. Missing fields,
+            # failed tools, future/stale readings and invalid payloads are not.
+            if verdict.complete:
+                return derived
+        return None
+
+    def _persist_mixed(self, program: Any, context: dict, names: list[str],
+                       reused: dict[str, dict],
+                       fresh: dict[str, dict]) -> str:
+        records = {name: (reused[name] if name in reused else fresh[name]) for name in names}
+        collection = {"source_digest": program.source_digest, "context": dict(context),
+                      "records": records}
+        if len(json.dumps(collection, ensure_ascii=False, sort_keys=True,
+                          allow_nan=False).encode("utf-8")) > MAX_COLLECTION_BYTES:
+            raise ValueError(f"Collection exceeds {MAX_COLLECTION_BYTES} stored bytes")
+        if not reused:
+            return self.service.store.put("collection", collection)
+        entries = [("observation", record, record["run_id"])
+                   for record in reused.values()]
+        entries.append(("collection", collection, None))
+        return self.service.store.put_batch(entries)[-1]
+
+    def assess(self, entry_id: str, claim: str, *, context: dict | None = None,
+               now: str | None = None,
+               reuse: Literal["compatible", "fresh"] = "compatible") -> dict:
+        """Collect the complete claim graph and assess it under a pinned revision.
+
+        ``context`` is an operator-side override. Model-facing routes should
+        pass only the registered entry ID and claim, using its default context.
+        ``fresh`` forces acquisition of every planned evidence declaration.
+        """
+        if reuse not in ("compatible", "fresh"):
+            raise ValueError("reuse must be 'compatible' or 'fresh'")
+        if now is not None and not isinstance(now, str):
+            raise ValueError("now must be an ISO-8601 timestamp with a timezone")
+        instant = parse_time(utc_now() if now is None else now)
+        entry = self.catalogue.get(entry_id, include_source=True)
+        if not isinstance(claim, str) or claim not in entry["claims"]:
+            raise ValueError(f"Claim {claim!r} is not selected in registered entry {entry_id!r}")
+        if entry["method_registry_fingerprint"] != self.service.method_registry.fingerprint:
+            raise ValueError("Registered source method registry differs from the current host")
+        selected_context = entry["context"] if context is None else context
+        if not isinstance(selected_context, dict):
+            raise ValueError("context must be a JSON object")
+        canonical_digest(selected_context)
+
+        source = entry["source"]
+        plan = self.service.plan(source, claim)
+        names = plan["evidence_ids"]
+        if len(names) > self.service.limits.collection_evidence:
+            raise ValueError(f"Collection exceeds {self.service.limits.collection_evidence} evidence requests")
+        program = self.service.parse(source)
+        if program.source_digest != entry["source_digest"]:
+            raise ValueError("Registered source digest differs from its snapshot")
+
+        reused: dict[str, dict] = {}
+        bindings: dict[str, str | None] = {}
+        executions: dict[str, str | None] = {}
+        if reuse == "compatible":
+            bindings = self.service.current_binding_digests(program)
+            executions = self.service.current_execution_digests(program)
+            for name in names:
+                candidate = self._candidate(
+                    program, selected_context, name, instant=instant,
+                    binding_digest=bindings[name], execution_digest=executions[name],
+                )
+                if candidate is not None:
+                    reused[name] = candidate
+
+        missing = [name for name in names if name not in reused]
+        collection = (self.service.collect(source, selected_context, missing)
+                      if missing or not reused else None)
+        fresh = {} if collection is None else dict(collection["records"])
+        if reused:
+            # Acquisition can take long enough for a reading to expire or the
+            # operator's tool/process environment to change. Recheck before
+            # binding old records to the new collection.
+            if now is None:
+                instant = parse_time(utc_now())
+            current_bindings = self.service.current_binding_digests(program)
+            current_executions = self.service.current_execution_digests(program)
+            expired = [name for name, record in reused.items()
+                       if bindings[name] != current_bindings[name]
+                       or executions[name] != current_executions[name]
+                       or not assess_evidence_record(
+                           program, name, record, instant=instant, context=selected_context,
+                           environment_matched=True,
+                           expected_tool_binding_digest=current_bindings[name],
+                           check_current_binding=True,
+                       ).complete]
+            if expired:
+                for name in expired:
+                    reused.pop(name)
+                replacement = self.service.collect(
+                    source, selected_context, expired,
+                )
+                fresh.update(replacement["records"])
+
+        if reused:
+            collection_id = self._persist_mixed(program, selected_context, names, reused, fresh)
+        elif collection is not None and set(collection["records"]) == set(names) and set(fresh) == set(names):
+            collection_id = collection["collection_id"]
+        else:
+            # Multiple partial acquisitions form one source-bound collection.
+            collection_id = self._persist_mixed(program, selected_context, names, {}, fresh)
+
+        assessed_at = now if now is not None else utc_now()
+        assessment = self.service.reason(source, selected_context, collection_id, now=assessed_at)
+        packet = self.service.packet(assessment["assessment_id"], claim)
+        return {
+            "schema": "EAL/registered-assessment/1", "entry_id": entry_id,
+            "claim": claim, "source_digest": program.source_digest,
+            "context_fingerprint": assessment["context_fingerprint"],
+            "collection_id": collection_id, "assessment_id": assessment["assessment_id"],
+            "assessed_at": assessment["assessed_at"],
+            "status": assessment["claims"][claim]["status"],
+            "reused_count": len(reused), "collected_count": len(fresh),
+            "packet": packet, "full_explanation": packet["full_explanation"],
+        }
+
+    def history(self, entry_id: str, *, source_digest: str | None = None,
+                limit: int = 50) -> dict:
+        """Find prior exact-source/context assessments by durable IDs."""
+        return self.catalogue.runs(entry_id, source_digest=source_digest, limit=limit)