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

eal/__init__.py

@@ -0,0 +1,3 @@
+"""Engineering Argument Language: explicit, revisable engineering reasoning."""
+
+__version__ = "3.2.3"

eal/abstractions.py

@@ -0,0 +1,144 @@
+"""Closed, typed argument-pattern lowering without textual substitution."""
+from __future__ import annotations
+
+from dataclasses import replace
+
+from .model import Argument, ArgumentOrigin, Diagnostic, Pattern, Program
+from .limits import bounded, current_limits
+
+MAX_PATTERN_APPLICATIONS = 1000
+MAX_EXPANDED_REFERENCES = 100_000
+PARAMETER_KINDS = frozenset({"claim", "reasoning", "evidence", "assumption"})
+
+
+def _references(pattern: Pattern):
+    """Yield each body reference with the required kind of its clause."""
+    yield pattern.conclusion, "claim", "conclusion"
+    yield pattern.reasoning, "reasoning", "reasoning"
+    for field, kind in (("evidence", "evidence"), ("assumptions", "assumption"),
+                        ("premises", "claim")):
+        for name in getattr(pattern, field):
+            yield name, kind, field
+    if pattern.binding is not None:
+        yield pattern.binding, "evidence", "binding"
+
+
+@bounded
+def lower_patterns(program: Program) -> Program:
+    """Check all definitions, resolve named arguments and expand valid uses.
+
+    Authored lexical trees use the compound composition pass. Direct core IR
+    supports compact closed patterns; substitution acts on typed references.
+    Invalid lowering records diagnostics; static validation blocks execution.
+    Reapplying this pass is idempotent, including its declaration accounting.
+    """
+    if program.authored is not None:
+        from .composition import lower_program
+        return lower_program(program)
+    diagnostics: list[Diagnostic] = []
+
+    def error(code, message, declaration, expected=None, actual=None):
+        diagnostics.append(Diagnostic(code, message, declaration,
+                                      program.locations.get(declaration), expected, actual))
+
+    tables = {"claim": program.claims, "reasoning": program.reasoning,
+              "evidence": program.evidence, "assumption": program.assumptions,
+              "environment": program.environments, "tool": program.tools,
+              "argument": program.arguments, "objection": program.objections,
+              "pattern": program.patterns, "application": program.applications}
+    symbol_kinds = {name: kind for kind, table in tables.items() for name in table}
+    invalid_patterns = set()
+    for pattern in program.patterns.values():
+        before = len(diagnostics)
+        if not (pattern.evidence or pattern.assumptions or pattern.premises):
+            error("empty_pattern", "An argument pattern requires evidence, assumptions or premise claims",
+                  pattern.name)
+        parameters = {}
+        for parameter in pattern.parameters:
+            if parameter.name in parameters:
+                error("duplicate_pattern_parameter",
+                      f"Parameter {parameter.name!r} is declared more than once", pattern.name)
+            parameters[parameter.name] = parameter.kind
+            if parameter.kind not in PARAMETER_KINDS:
+                error("invalid_pattern_parameter_kind",
+                      f"Parameter {parameter.name!r} requires claim, reasoning, evidence or assumption",
+                      pattern.name, "claim | reasoning | evidence | assumption", parameter.kind)
+        for name, expected, clause in _references(pattern):
+            actual = parameters.get(name)
+            if actual is None:
+                error("unbound_pattern_reference",
+                      f"{clause} reference {name!r} must name a declared parameter; global capture is forbidden",
+                      pattern.name, expected, "undeclared parameter")
+            elif actual != expected:
+                error("pattern_reference_kind",
+                      f"{clause} parameter {name!r} has kind {actual!r}; expected {expected!r}",
+                      pattern.name, expected, actual)
+        if len(diagnostics) > before or pattern.name in program.duplicates:
+            invalid_patterns.add(pattern.name)
+
+    # Drop previously generated arguments so repeat lowering never copies output
+    # back into the authored input or mistakes it for a name collision.
+    arguments = {name: argument for name, argument in program.arguments.items()
+                 if argument.origin is None}
+    authored_names = set().union(*(set(table) for kind, table in tables.items()
+                                  if kind not in ("argument", "application")), arguments)
+    old_expansion_count = len(program.arguments) - len(arguments)
+    if len(program.applications) > current_limits().applications:
+        declaration = next(iter(program.applications))
+        error("resource_limit", f"At most {current_limits().applications} pattern applications are supported",
+              declaration)
+        return replace(program, arguments=arguments, lowering_diagnostics=tuple(diagnostics),
+                       declaration_count=program.declaration_count - old_expansion_count)
+
+    expanded_references = 0
+    for application in program.applications.values():
+        before = len(diagnostics)
+        pattern = program.patterns.get(application.pattern)
+        if pattern is None:
+            error("unknown_pattern", f"Unknown pattern {application.pattern!r}", application.name,
+                  "pattern", symbol_kinds.get(application.pattern, "unknown reference"))
+            continue
+        if application.name in authored_names or application.name in program.duplicates:
+            error("generated_symbol_collision",
+                  f"Generated argument {application.name!r} collides with another declaration", application.name)
+        if pattern.name in invalid_patterns:
+            error("invalid_pattern", f"Pattern {pattern.name!r} has an invalid definition", application.name)
+            continue
+        parameters = {parameter.name: parameter.kind for parameter in pattern.parameters}
+        bindings = {}
+        for binding in application.arguments:
+            if binding.name in bindings:
+                error("duplicate_pattern_argument",
+                      f"Argument {binding.name!r} is supplied more than once", application.name)
+            bindings[binding.name] = binding.reference
+            expected = parameters.get(binding.name)
+            if expected is None:
+                error("unknown_pattern_argument",
+                      f"Pattern {pattern.name!r} has no parameter {binding.name!r}", application.name)
+            elif binding.reference not in tables[expected]:
+                actual = symbol_kinds.get(binding.reference, "unknown reference")
+                error("pattern_argument_kind",
+                      f"Argument {binding.name!r} must reference {expected}; {binding.reference!r} is {actual}",
+                      application.name, expected, actual)
+        for missing in sorted(parameters.keys() - bindings.keys()):
+            error("missing_pattern_argument",
+                  f"Pattern {pattern.name!r} requires argument {missing!r}", application.name,
+                  parameters[missing], "missing")
+        if len(diagnostics) != before:
+            continue
+        reference_count = sum(1 for _ in _references(pattern))
+        if expanded_references + reference_count > current_limits().expanded_references:
+            error("resource_limit",
+                  f"Pattern expansion permits at most {current_limits().expanded_references} references", application.name)
+            break
+        expanded_references += reference_count
+        arguments[application.name] = Argument(
+            application.name, bindings[pattern.conclusion], bindings[pattern.reasoning],
+            tuple(bindings[name] for name in pattern.evidence),
+            tuple(bindings[name] for name in pattern.assumptions),
+            tuple(bindings[name] for name in pattern.premises),
+            bindings[pattern.binding] if pattern.binding is not None else None,
+            ArgumentOrigin(pattern.name, application.name))
+    new_expansion_count = sum(argument.origin is not None for argument in arguments.values())
+    return replace(program, arguments=arguments, lowering_diagnostics=tuple(diagnostics),
+                   declaration_count=program.declaration_count - old_expansion_count + new_expansion_count)

eal/acquisition_coordination.py

@@ -0,0 +1,80 @@
+"""Own local acquisition leases that survive their server through inherited descriptors."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+import os
+from pathlib import Path
+import stat
+import time
+
+from filelock import FileLock, Timeout
+
+
+_ACTIVE_DESCRIPTOR: ContextVar[int | None] = ContextVar("eal_acquisition_descriptor", default=None)
+
+
+def inherited_acquisition_descriptor() -> int | None:
+    """Borrow the current lease for a command supervisor; ownership stays with the caller."""
+    return _ACTIVE_DESCRIPTOR.get()
+
+
+class WorkspaceAcquisition:
+    """Exclude local acquisitions until every owning process closes its lease."""
+
+    def __init__(self, workspace: Path):
+        directory = workspace / ".eal"
+        directory.mkdir(parents=True, exist_ok=True)
+        details = directory.lstat()
+        if not stat.S_ISDIR(details.st_mode):
+            raise PermissionError("The MCP acquisition directory must be a regular directory")
+        if os.name == "posix" and (details.st_uid != os.getuid() or details.st_mode & 0o022):
+            raise PermissionError("The MCP acquisition directory must be owned by the process and not writable by others")
+        self.path = directory / "mcp-acquisition.lock"
+        if self.path.is_symlink():
+            raise PermissionError("The MCP acquisition lock must not be a symlink")
+
+    @contextmanager
+    def hold(self, *, timeout: float = 120):
+        if os.name != "posix":
+            # The command adapter requires POSIX; file-only operations retain
+            # the portable server-process exclusion used by FileLock.
+            with FileLock(self.path, timeout=timeout, mode=0o600):
+                yield
+            return
+        import fcntl
+
+        try:
+            existing = self.path.lstat()
+        except FileNotFoundError:
+            pass
+        else:
+            if not stat.S_ISREG(existing.st_mode):
+                raise PermissionError("The MCP acquisition lock must be a private regular file")
+        descriptor = os.open(self.path, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK, 0o600)
+        try:
+            details = os.fstat(descriptor)
+            named = self.path.lstat()
+            if (not stat.S_ISREG(details.st_mode) or details.st_uid != os.getuid()
+                    or stat.S_IMODE(details.st_mode) != 0o600 or details.st_nlink != 1
+                    or (details.st_dev, details.st_ino) != (named.st_dev, named.st_ino)):
+                raise PermissionError("The MCP acquisition lock must be a private regular file")
+            deadline = time.monotonic() + timeout
+            while True:
+                try:
+                    fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    break
+                except BlockingIOError:
+                    if time.monotonic() >= deadline:
+                        raise Timeout(str(self.path)) from None
+                    time.sleep(min(0.05, max(0, deadline - time.monotonic())))
+            token = _ACTIVE_DESCRIPTOR.set(descriptor)
+            try:
+                yield
+            finally:
+                _ACTIVE_DESCRIPTOR.reset(token)
+        finally:
+            # flock belongs to the open file description. Closing this copy,
+            # rather than LOCK_UN, preserves ownership in a live supervisor.
+            os.close(descriptor)

eal/api_load_methods.py

@@ -0,0 +1,77 @@
+"""Optional host-installed, typed method for a finite API load-test report.
+
+The source and acquisition host decide whether a report applies to the target
+run. This method only computes three inclusive sample criteria from statistics.
+"""
+from __future__ import annotations
+
+from eal.methods import MethodContract, default_registry
+
+
+NUMBER = {"type": "number", "minimum": 0, "maximum": 1e100}
+OPTIONAL_NUMBER = {"anyOf": [NUMBER, {"type": "null"}]}
+OPTIONAL_PERCENT = {"anyOf": [{"type": "number", "minimum": 0, "maximum": 100},
+                              {"type": "null"}]}
+OPTIONAL_INTEGER = {"anyOf": [{"type": "integer", "minimum": 0, "maximum": 1_000_000_000},
+                              {"type": "null"}]}
+OPTIONAL_BOOLEAN = {"anyOf": [{"type": "boolean"}, {"type": "null"}]}
+REPORT_FIELDS = {
+    "request_count": OPTIONAL_INTEGER,
+    "p95_ms": OPTIONAL_NUMBER,
+    "error_rate_percent": OPTIONAL_PERCENT,
+    "report_valid": {"type": "boolean"},
+    "identity_matches": OPTIONAL_BOOLEAN,
+    "complete_records": OPTIONAL_BOOLEAN,
+    "consistent_records": OPTIONAL_BOOLEAN,
+    "age_seconds": OPTIONAL_NUMBER,
+    "failed_requests": {"type": "integer", "minimum": 0, "maximum": 1_000_000_000},
+}
+RESULT_FIELDS = {"sample_size_met": {"type": "boolean"},
+                 "latency_met": OPTIONAL_BOOLEAN, "error_limit_met": OPTIONAL_BOOLEAN,
+                 "passes": {"type": "boolean"}, "fails": {"type": "boolean"}}
+
+
+def assess_api_limits(report: dict) -> dict:
+    """Interpret finite sample statistics; negative findings are results.
+
+    An empty but otherwise complete requested run fails the sample-size
+    condition. Nonempty runs must have computed finite statistics. The caller's
+    evidence predicates decide report validity, identity and freshness.
+    """
+    count = report["request_count"]
+    if count is None:
+        raise ValueError("An admitted report requires a measured request count")
+    if count:
+        if report["p95_ms"] is None or report["error_rate_percent"] is None:
+            raise ValueError("A nonempty report requires both measured statistics")
+        latency = report["p95_ms"] <= 200
+        errors = report["error_rate_percent"] <= 1
+    else:
+        # No observed latency or error rate is asserted for an empty run.
+        if report["p95_ms"] is not None or report["error_rate_percent"] is not None:
+            raise ValueError("An empty report cannot carry latency or error-rate statistics")
+        latency = errors = None
+    sample = count >= 100
+    results = {"sample_size_met": sample, "latency_met": latency,
+               "error_limit_met": errors}
+    return {**results, "passes": all(value is True for value in results.values()),
+            "fails": any(value is False for value in results.values())}
+
+
+CONTRACT = MethodContract(
+    identifier="engineering/api-load-criteria/1", evidence_kind="api_report",
+    input_schema={"type": "object", "properties": REPORT_FIELDS,
+                  "required": ["request_count", "p95_ms", "error_rate_percent"],
+                  "additionalProperties": False},
+    query_schema={"type": "object", "properties": {}, "required": [], "additionalProperties": False},
+    output_schema={"type": "object", "properties": RESULT_FIELDS,
+                   "required": list(RESULT_FIELDS), "additionalProperties": False},
+    outputs={name: "boolean" for name in ("sample_size_met", "passes", "fails")},
+    quantities=(), exact_unit=False, implementation=assess_api_limits,
+    implementation_version="eal-api-load-criteria-1",
+)
+
+
+def registry():
+    """Trusted MCP operator factory; the EAL source only names the method."""
+    return default_registry().with_method(CONTRACT)