tigrcorn-contract 0.3.16.dev12__tar.gz → 0.3.17.dev1__tar.gz

{tigrcorn_contract-0.3.16.dev12 → tigrcorn_contract-0.3.17.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrcorn-contract
-Version: 0.3.16.dev12
+Version: 0.3.17.dev1
 Summary: tigr-asgi-contract adapters and runtime-boundary classification for Tigrcorn ASGI3, WebSocket, and WebTransport surfaces.
 Author-email: Jacob Stewart <jacob@swarmauri.com>
 License: Apache License
@@ -186,8 +186,8 @@ Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: tigrcorn-core==0.3.16.dev12
-Requires-Dist: tigrcorn-asgi==0.3.16.dev12
+Requires-Dist: tigrcorn-core==0.3.17.dev1
+Requires-Dist: tigrcorn-asgi==0.3.17.dev1
 Requires-Dist: tigr-asgi-contract>=0.3.2
 Dynamic: license-file
 

{tigrcorn_contract-0.3.16.dev12 → tigrcorn_contract-0.3.17.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tigrcorn-contract"
-version = "0.3.16.dev12"
+version = "0.3.17.dev1"
 description = "tigr-asgi-contract adapters and runtime-boundary classification for Tigrcorn ASGI3, WebSocket, and WebTransport surfaces."
 readme = "README.md"
 requires-python = ">=3.10,<3.15"
@@ -29,8 +29,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "tigrcorn-core==0.3.16.dev12",
-  "tigrcorn-asgi==0.3.16.dev12",
+  "tigrcorn-core==0.3.17.dev1",
+  "tigrcorn-asgi==0.3.17.dev1",
   "tigr-asgi-contract>=0.3.2",
 ]
 

{tigrcorn_contract-0.3.16.dev12 → tigrcorn_contract-0.3.17.dev1}/src/tigrcorn_contract/__init__.py

@@ -96,6 +96,29 @@ from .projection import (
     project_send_event,
     validate_projected_event,
 )
+from .semantics import (
+    SemanticObservation,
+    channel_lifecycle_capabilities,
+    enforce_semantic_transition,
+    observe_backpressure as observe_contract_backpressure,
+    observe_channel_lifecycle,
+    observe_completion,
+    observe_disconnect,
+    observe_transport_cancellation,
+    require_channel_readable,
+    require_channel_writable,
+)
+from .registry import (
+    ContractRecord,
+    ContractStability,
+    ContractTraceability,
+    ContractTraceabilityError,
+    TraceabilityStatus,
+    contract_records,
+    export_contract_registry,
+    validate_contract_traceability,
+    validate_registry,
+)
 from .scopes import SUPPORTED_SCOPE_TYPES, contract_scope, validate_scope
 
 __all__ = [
@@ -103,6 +126,10 @@ __all__ = [
     "CompletionLevel",
     "CompletionStatus",
     "ConnectionIdentity",
+    "ContractRecord",
+    "ContractStability",
+    "ContractTraceability",
+    "ContractTraceabilityError",
     "EndpointMetadata",
     "FamilyCapability",
     "GenericDatagramRuntime",
@@ -112,23 +139,29 @@ __all__ = [
     "HTTPFeatureContractMap",
     "SUPPORTED_SCOPE_TYPES",
     "SecurityMetadata",
+    "SemanticObservation",
     "EventProjection",
     "ScopeProjection",
     "StreamIdentity",
+    "TraceabilityStatus",
     "UnitIdentity",
     "alt_svc_contract_map",
     "asgi3_extensions",
     "asgi3_compat_scope",
     "asgi_extension_bridge",
+    "channel_lifecycle_capabilities",
     "classify_binding",
     "compatibility_feature_parity",
     "contract_scope",
+    "contract_records",
     "content_coding_contract_map",
     "datagram_identity",
     "datagram_receive",
     "datagram_send",
     "emit_complete",
     "endpoint_metadata",
+    "export_contract_registry",
+    "enforce_semantic_transition",
     "early_hints_contract_map",
     "family_capability",
     "http_disconnect",
@@ -145,6 +178,11 @@ __all__ = [
     "lifespan_startup_failed",
     "map_contract_event",
     "observability_contract_metadata",
+    "observe_contract_backpressure",
+    "observe_channel_lifecycle",
+    "observe_completion",
+    "observe_disconnect",
+    "observe_transport_cancellation",
     "proxy_normalization_contract_map",
     "product_surface_status",
     "product_surface_excluded",
@@ -152,6 +190,8 @@ __all__ = [
     "project_receive_event",
     "project_scope_classification",
     "project_send_event",
+    "require_channel_readable",
+    "require_channel_writable",
     "require_lossless_metadata",
     "require_product_boundary_exclusion",
     "require_product_runtime_available",
@@ -165,12 +205,14 @@ __all__ = [
     "trailers_contract_map",
     "unit_identity",
     "validate_binding_legality",
+    "validate_contract_traceability",
     "validate_connection_identity",
     "validate_datagram_event",
     "validate_endpoint_metadata",
     "validate_event_order",
     "validate_projected_event",
     "validate_security_metadata",
+    "validate_registry",
     "validate_scope",
     "validate_stream_event",
     "validate_stream_identity",

{tigrcorn_contract-0.3.16.dev12 → tigrcorn_contract-0.3.17.dev1}/src/tigrcorn_contract/events.py

@@ -47,7 +47,11 @@ WEBTRANSPORT_EVENT_MAP = {
 
 class CompletionLevel(StrEnum):
     ACCEPTED_BY_RUNTIME = "accepted_by_runtime"
+    QUEUED_FOR_TRANSPORT = "queued_for_transport"
     FLUSHED_TO_TRANSPORT = "flushed_to_transport"
+    PEER_ACKNOWLEDGED = "peer_acknowledged"
+    FAILED_DURING_EMIT = "failed_during_emit"
+    ABORTED_BY_PEER = "aborted_by_peer"
 
 
 class CompletionStatus(StrEnum):
@@ -436,9 +440,12 @@ def _normalize_completion_level(level: str) -> str:
     aliases = {
         "buffered": CompletionLevel.ACCEPTED_BY_RUNTIME.value,
         "accepted": CompletionLevel.ACCEPTED_BY_RUNTIME.value,
+        "queued": CompletionLevel.QUEUED_FOR_TRANSPORT.value,
         "flushed": CompletionLevel.FLUSHED_TO_TRANSPORT.value,
         "transport": CompletionLevel.FLUSHED_TO_TRANSPORT.value,
-        "acknowledged": CompletionLevel.FLUSHED_TO_TRANSPORT.value,
+        "acknowledged": CompletionLevel.PEER_ACKNOWLEDGED.value,
+        "failed": CompletionLevel.FAILED_DURING_EMIT.value,
+        "aborted": CompletionLevel.ABORTED_BY_PEER.value,
     }
     return aliases.get(level, level)
 

tigrcorn_contract-0.3.17.dev1/src/tigrcorn_contract/registry.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Iterable
+
+
+class ContractStability(str, Enum):
+    EXPERIMENTAL = "experimental"
+    PREVIEW = "preview"
+    STABLE = "stable"
+    CERTIFIED = "certified"
+    DEPRECATED = "deprecated"
+
+
+class TraceabilityStatus(str, Enum):
+    COMPLETE = "complete"
+    PARTIAL = "partial"
+    PROVISIONAL = "provisional"
+    FAILED = "failed"
+
+
+class ContractTraceabilityError(ValueError):
+    """Raised when a contract claims certification without required proof."""
+
+
+@dataclass(frozen=True, slots=True)
+class ContractTraceability:
+    rfcs: tuple[str, ...] = ()
+    spec_ids: tuple[str, ...] = ()
+    implementation_refs: tuple[str, ...] = ()
+    test_ids: tuple[str, ...] = ()
+    evidence_ids: tuple[str, ...] = ()
+    negative_test_ids: tuple[str, ...] = ()
+    status: TraceabilityStatus = TraceabilityStatus.PARTIAL
+    release_certified: bool = False
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "rfcs": list(self.rfcs),
+            "spec_ids": list(self.spec_ids),
+            "implementation_refs": list(self.implementation_refs),
+            "test_ids": list(self.test_ids),
+            "evidence_ids": list(self.evidence_ids),
+            "negative_test_ids": list(self.negative_test_ids),
+            "status": self.status.value,
+            "release_certified": self.release_certified,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ContractRecord:
+    contract_id: str
+    version: str
+    title: str
+    owner_package: str
+    owner_module: str
+    stability: ContractStability
+    implemented: bool
+    certified: bool
+    traceability: ContractTraceability
+    replacement_contract_id: str | None = None
+    retirement_note: str | None = None
+    tags: tuple[str, ...] = field(default_factory=tuple)
+
+    def as_dict(self) -> dict[str, Any]:
+        payload = {
+            "contract_id": self.contract_id,
+            "version": self.version,
+            "title": self.title,
+            "owner_package": self.owner_package,
+            "owner_module": self.owner_module,
+            "stability": self.stability.value,
+            "implemented": self.implemented,
+            "certified": self.certified,
+            "traceability": self.traceability.as_dict(),
+            "tags": list(self.tags),
+        }
+        if self.replacement_contract_id is not None:
+            payload["replacement_contract_id"] = self.replacement_contract_id
+        if self.retirement_note is not None:
+            payload["retirement_note"] = self.retirement_note
+        return payload
+
+
+def _traceability_status(
+    *,
+    rfcs: Iterable[str] = (),
+    spec_ids: Iterable[str] = (),
+    implementation_refs: Iterable[str] = (),
+    test_ids: Iterable[str] = (),
+    evidence_ids: Iterable[str] = (),
+    negative_test_ids: Iterable[str] = (),
+    provisional: bool = False,
+) -> ContractTraceability:
+    traceability = ContractTraceability(
+        rfcs=tuple(sorted(rfcs)),
+        spec_ids=tuple(sorted(spec_ids)),
+        implementation_refs=tuple(sorted(implementation_refs)),
+        test_ids=tuple(sorted(test_ids)),
+        evidence_ids=tuple(sorted(evidence_ids)),
+        negative_test_ids=tuple(sorted(negative_test_ids)),
+        status=TraceabilityStatus.PROVISIONAL if provisional else TraceabilityStatus.PARTIAL,
+    )
+    complete = all(
+        (
+            traceability.rfcs,
+            traceability.spec_ids,
+            traceability.implementation_refs,
+            traceability.test_ids,
+            traceability.evidence_ids,
+            traceability.negative_test_ids,
+        )
+    )
+    if complete and not provisional:
+        return ContractTraceability(
+            rfcs=traceability.rfcs,
+            spec_ids=traceability.spec_ids,
+            implementation_refs=traceability.implementation_refs,
+            test_ids=traceability.test_ids,
+            evidence_ids=traceability.evidence_ids,
+            negative_test_ids=traceability.negative_test_ids,
+            status=TraceabilityStatus.COMPLETE,
+            release_certified=True,
+        )
+    return traceability
+
+
+_CONTRACTS: tuple[ContractRecord, ...] = (
+    ContractRecord(
+        contract_id="asgi.http.scope",
+        version="1.0",
+        title="HTTP scope contract",
+        owner_package="tigrcorn-contract",
+        owner_module="tigrcorn_contract.scopes",
+        stability=ContractStability.CERTIFIED,
+        implemented=True,
+        certified=True,
+        traceability=_traceability_status(
+            rfcs=("RFC 9110", "RFC 9112"),
+            spec_ids=("spc:1021",),
+            implementation_refs=("tigrcorn_contract.scopes:contract_scope",),
+            test_ids=("tst:contract-http-scope", "tst:contract-unsupported-scope-rejection"),
+            evidence_ids=("evd:contract-http-scope-pytest", "evd:contract-unsupported-scope-rejection-pytest"),
+            negative_test_ids=("tst:contract-unsupported-scope-rejection",),
+        ),
+        tags=("http", "scope"),
+    ),
+    ContractRecord(
+        contract_id="asgi.websocket.events",
+        version="1.0",
+        title="WebSocket event contract",
+        owner_package="tigrcorn-contract",
+        owner_module="tigrcorn_contract.events",
+        stability=ContractStability.STABLE,
+        implemented=True,
+        certified=False,
+        traceability=_traceability_status(
+            rfcs=("RFC 6455",),
+            spec_ids=("spc:1021",),
+            implementation_refs=("tigrcorn_contract.events:websocket_connect",),
+            test_ids=("tst:contract-websocket-event-map",),
+            evidence_ids=("evd:contract-websocket-event-map-pytest",),
+        ),
+        tags=("websocket", "events"),
+    ),
+    ContractRecord(
+        contract_id="webtransport.stream.identity",
+        version="0.9",
+        title="WebTransport stream identity contract",
+        owner_package="tigrcorn-contract",
+        owner_module="tigrcorn_contract.metadata",
+        stability=ContractStability.PREVIEW,
+        implemented=True,
+        certified=False,
+        traceability=_traceability_status(
+            rfcs=("RFC 9220",),
+            spec_ids=("spc:1011",),
+            implementation_refs=("tigrcorn_contract.metadata:stream_identity",),
+            test_ids=("tst:contract-webtransport-stream-identity",),
+            evidence_ids=("evd:contract-webtransport-stream-identity-pytest",),
+            provisional=True,
+        ),
+        tags=("webtransport", "identity"),
+    ),
+    ContractRecord(
+        contract_id="operator.contract.registry",
+        version="0.1",
+        title="Contract registry export contract",
+        owner_package="tigrcorn-contract",
+        owner_module="tigrcorn_contract.registry",
+        stability=ContractStability.EXPERIMENTAL,
+        implemented=True,
+        certified=False,
+        traceability=_traceability_status(
+            spec_ids=("spc:2058",),
+            implementation_refs=("tigrcorn_contract.registry:export_contract_registry",),
+            test_ids=("tst:contract-registry-record-shape", "tst:contract-registry-deterministic-export"),
+            evidence_ids=("evd:contract-registry-and-traceability-test-plan",),
+        ),
+        tags=("operator", "registry"),
+    ),
+    ContractRecord(
+        contract_id="asgi.http.scope.v0",
+        version="0.9",
+        title="Deprecated HTTP scope contract",
+        owner_package="tigrcorn-contract",
+        owner_module="tigrcorn_contract.scopes",
+        stability=ContractStability.DEPRECATED,
+        implemented=False,
+        certified=False,
+        traceability=_traceability_status(spec_ids=("spc:1021",)),
+        replacement_contract_id="asgi.http.scope",
+        retirement_note="Replaced by the certified 1.0 HTTP scope contract.",
+        tags=("http", "scope"),
+    ),
+)
+
+
+def contract_records() -> tuple[ContractRecord, ...]:
+    return tuple(sorted(_CONTRACTS, key=lambda item: item.contract_id))
+
+
+def export_contract_registry() -> dict[str, Any]:
+    return {
+        "schema_version": "1.0",
+        "registry": "tigrcorn.contracts",
+        "contracts": [record.as_dict() for record in contract_records()],
+    }
+
+
+def validate_contract_traceability(record: ContractRecord) -> None:
+    traceability = record.traceability
+    missing: list[str] = []
+    for field_name in ("rfcs", "spec_ids", "implementation_refs", "test_ids", "evidence_ids", "negative_test_ids"):
+        if not getattr(traceability, field_name):
+            missing.append(field_name)
+    if record.certified and (traceability.status != TraceabilityStatus.COMPLETE or missing):
+        raise ContractTraceabilityError(
+            f"certified contract {record.contract_id!r} lacks complete traceability: {', '.join(missing)}"
+        )
+    if record.certified and record.stability != ContractStability.CERTIFIED:
+        raise ContractTraceabilityError(f"certified contract {record.contract_id!r} must use certified stability")
+
+
+def validate_registry(records: Iterable[ContractRecord] | None = None) -> None:
+    for record in records if records is not None else contract_records():
+        validate_contract_traceability(record)

tigrcorn_contract-0.3.17.dev1/src/tigrcorn_contract/semantics.py

@@ -0,0 +1,348 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from tigrcorn_core.errors import ProtocolError
+
+try:  # pragma: no cover - covered when the newer contract package is installed.
+    from tigr_asgi_contract import semantic_domain as _contract_semantic_domain
+    from tigr_asgi_contract import semantic_transition_target as _contract_transition_target
+    from tigr_asgi_contract import validate_semantic_transition as _contract_validate_transition
+except Exception:  # pragma: no cover - published contract fallback.
+    _contract_semantic_domain = None
+    _contract_transition_target = None
+    _contract_validate_transition = None
+
+
+_FALLBACK_TRANSITIONS = {
+    ("completion", "accepted_by_runtime", "completion.queued"): "queued_for_transport",
+    ("completion", "queued_for_transport", "completion.flushed"): "flushed_to_transport",
+    ("completion", "flushed_to_transport", "completion.peer_acknowledged"): "peer_acknowledged",
+    ("completion", "accepted_by_runtime", "completion.failed"): "failed_during_emit",
+    ("completion", "queued_for_transport", "completion.failed"): "failed_during_emit",
+    ("completion", "flushed_to_transport", "completion.failed"): "failed_during_emit",
+    ("completion", "accepted_by_runtime", "completion.peer_aborted"): "aborted_by_peer",
+    ("completion", "queued_for_transport", "completion.peer_aborted"): "aborted_by_peer",
+    ("completion", "flushed_to_transport", "completion.peer_aborted"): "aborted_by_peer",
+    ("backpressure", "writable", "backpressure.congested"): "congested",
+    ("backpressure", "congested", "backpressure.saturated"): "saturated",
+    ("backpressure", "saturated", "backpressure.draining"): "draining",
+    ("backpressure", "draining", "backpressure.resumed"): "resumed",
+    ("backpressure", "resumed", "backpressure.writable"): "writable",
+    ("backpressure", "congested", "backpressure.resumed"): "resumed",
+    ("cancellation", "requested", "cancellation.propagated"): "propagated",
+    ("cancellation", "propagated", "cancellation.acknowledged"): "acknowledged",
+    ("cancellation", "acknowledged", "cancellation.completed"): "completed",
+    ("cancellation", "requested", "cancellation.ignored"): "ignored",
+    ("cancellation", "propagated", "cancellation.failed"): "failed",
+    ("cancellation", "acknowledged", "cancellation.failed"): "failed",
+    ("disconnect", "graceful", "disconnect.peer_reset"): "peer_reset",
+    ("disconnect", "graceful", "disconnect.transport_lost"): "transport_lost",
+    ("disconnect", "graceful", "disconnect.timeout"): "timeout",
+    ("disconnect", "graceful", "disconnect.protocol_error"): "protocol_error",
+    ("disconnect", "graceful", "disconnect.server_shutdown"): "server_shutdown",
+    ("channel_lifecycle", "initialized", "channel.opening"): "opening",
+    ("channel_lifecycle", "opening", "channel.opened"): "open",
+    ("channel_lifecycle", "open", "channel.read_closed"): "read_closed",
+    ("channel_lifecycle", "open", "channel.write_closed"): "write_closed",
+    ("channel_lifecycle", "open", "channel.closing"): "closing",
+    ("channel_lifecycle", "open", "channel.closed"): "closed",
+    ("channel_lifecycle", "open", "channel.failed"): "failed",
+    ("channel_lifecycle", "open", "channel.lost"): "lost",
+    ("channel_lifecycle", "read_closed", "channel.write_closed"): "closed",
+    ("channel_lifecycle", "read_closed", "channel.closing"): "closing",
+    ("channel_lifecycle", "read_closed", "channel.failed"): "failed",
+    ("channel_lifecycle", "read_closed", "channel.lost"): "lost",
+    ("channel_lifecycle", "write_closed", "channel.read_closed"): "closed",
+    ("channel_lifecycle", "write_closed", "channel.closing"): "closing",
+    ("channel_lifecycle", "write_closed", "channel.failed"): "failed",
+    ("channel_lifecycle", "write_closed", "channel.lost"): "lost",
+    ("channel_lifecycle", "closing", "channel.closed"): "closed",
+    ("channel_lifecycle", "closing", "channel.failed"): "failed",
+    ("channel_lifecycle", "closing", "channel.lost"): "lost",
+}
+
+_FALLBACK_CHANNEL_CAPABILITIES = {
+    "initialized": {"can_drain": False, "can_read": False, "can_write": False, "terminal": False},
+    "opening": {"can_drain": False, "can_read": False, "can_write": False, "terminal": False},
+    "open": {"can_drain": False, "can_read": True, "can_write": True, "terminal": False},
+    "read_closed": {"can_drain": True, "can_read": False, "can_write": True, "terminal": False},
+    "write_closed": {"can_drain": True, "can_read": True, "can_write": False, "terminal": False},
+    "closing": {"can_drain": True, "can_read": False, "can_write": False, "terminal": False},
+    "closed": {"can_drain": False, "can_read": False, "can_write": False, "terminal": True},
+    "failed": {"can_drain": False, "can_read": False, "can_write": False, "terminal": True},
+    "lost": {"can_drain": False, "can_read": False, "can_write": False, "terminal": True},
+}
+
+_DISCONNECT_CAUSE_EVENTS = {
+    "http.disconnect": "disconnect.peer_reset",
+    "websocket.close": "disconnect.peer_reset",
+    "websocket.disconnect": "disconnect.peer_reset",
+    "http2.rst_stream": "disconnect.peer_reset",
+    "http3.stream.reset": "disconnect.peer_reset",
+    "quic.stop_sending": "disconnect.peer_reset",
+    "quic.reset_stream": "disconnect.peer_reset",
+    "webtransport.close": "disconnect.peer_reset",
+    "webtransport.disconnect": "disconnect.peer_reset",
+    "transport.lost": "disconnect.transport_lost",
+    "tls.protocol_failure": "disconnect.protocol_error",
+    "protocol.error": "disconnect.protocol_error",
+    "timeout": "disconnect.timeout",
+    "server.shutdown": "disconnect.server_shutdown",
+    "worker.draining": "disconnect.server_shutdown",
+}
+
+_CANCELLATION_CAUSE_EVENTS = {
+    "client_disconnected": "cancellation.propagated",
+    "stream_reset": "cancellation.propagated",
+    "server_shutdown": "cancellation.propagated",
+    "timeout": "cancellation.propagated",
+    "worker_draining": "cancellation.propagated",
+}
+
+_CHANNEL_CAUSE_EVENTS = {
+    "open_requested": "channel.opening",
+    "opened": "channel.opened",
+    "h2.end_stream_received": "channel.read_closed",
+    "h2.end_stream_sent": "channel.write_closed",
+    "h2.half_closed_remote": "channel.read_closed",
+    "h2.half_closed_local": "channel.write_closed",
+    "h2.rst_stream": "channel.lost",
+    "h2.goaway": "channel.closing",
+    "h3.request_receive_closed": "channel.read_closed",
+    "h3.request_send_closed": "channel.write_closed",
+    "h3.request_cancelled": "channel.lost",
+    "h3.request_rejected": "channel.failed",
+    "h3.goaway": "channel.closing",
+    "h3.stream_error": "channel.failed",
+    "quic.receive_stream_closed": "channel.read_closed",
+    "quic.send_stream_closed": "channel.write_closed",
+    "quic.connection_close": "channel.closing",
+    "quic.draining": "channel.closing",
+    "quic.idle_timeout": "channel.lost",
+    "websocket.closing": "channel.closing",
+    "websocket.closed": "channel.closed",
+    "websocket.http2.tunnel_ended": "channel.closing",
+    "websocket.http3.tunnel_ended": "channel.closing",
+    "tcp.reset": "channel.lost",
+    "transport.lost": "channel.lost",
+    "protocol.error": "channel.failed",
+}
+
+_DIRECTIONAL_RESET_EVENTS = {
+    "h3.reset_stream",
+    "quic.reset_stream",
+}
+
+_DIRECTIONAL_STOP_EVENTS = {
+    "h3.stop_sending",
+    "quic.stop_sending",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticObservation:
+    domain: str
+    previous_state: str
+    event: str
+    state: str
+    source: str
+    detail: str | None = None
+
+    def as_dict(self) -> dict[str, str]:
+        payload = {
+            "domain": self.domain,
+            "event": self.event,
+            "previous_state": self.previous_state,
+            "source": self.source,
+            "state": self.state,
+        }
+        if self.detail:
+            payload["detail"] = self.detail
+        return payload
+
+
+def enforce_semantic_transition(
+    domain: str,
+    state: str,
+    event: str,
+    *,
+    source: str = "tigrcorn",
+    detail: str | None = None,
+) -> SemanticObservation:
+    next_state = _semantic_transition_target(domain, state, event)
+    return SemanticObservation(
+        domain=domain,
+        previous_state=state,
+        event=event,
+        state=next_state,
+        source=source,
+        detail=detail,
+    )
+
+
+def observe_completion(
+    state: str,
+    *,
+    queued: bool = False,
+    flushed: bool = False,
+    peer_acknowledged: bool = False,
+    failed: bool = False,
+    peer_aborted: bool = False,
+) -> SemanticObservation:
+    event = _single_event(
+        "completion",
+        {
+            "completion.queued": queued,
+            "completion.flushed": flushed,
+            "completion.peer_acknowledged": peer_acknowledged,
+            "completion.failed": failed,
+            "completion.peer_aborted": peer_aborted,
+        },
+    )
+    return enforce_semantic_transition("completion", state, event)
+
+
+def observe_backpressure(
+    state: str,
+    *,
+    queued_bytes: int,
+    high_watermark: int,
+    resume_watermark: int | None = None,
+) -> SemanticObservation:
+    if queued_bytes < 0 or high_watermark < 0:
+        raise ProtocolError("backpressure counters must be non-negative")
+    if resume_watermark is not None and resume_watermark < 0:
+        raise ProtocolError("resume watermark must be non-negative")
+    if state == "writable" and queued_bytes >= high_watermark:
+        event = "backpressure.congested"
+    elif state == "congested" and queued_bytes >= high_watermark:
+        event = "backpressure.saturated"
+    elif state == "saturated":
+        event = "backpressure.draining"
+    elif state in {"congested", "draining"} and resume_watermark is not None and queued_bytes <= resume_watermark:
+        event = "backpressure.resumed"
+    elif state == "resumed":
+        event = "backpressure.writable"
+    else:
+        raise ProtocolError(f"no backpressure semantic transition for state {state!r}")
+    return enforce_semantic_transition("backpressure", state, event)
+
+
+def observe_disconnect(state: str, cause: str) -> SemanticObservation:
+    try:
+        event = _DISCONNECT_CAUSE_EVENTS[cause]
+    except KeyError as exc:
+        raise ProtocolError(f"unsupported disconnect cause: {cause!r}") from exc
+    return enforce_semantic_transition("disconnect", state, event)
+
+
+def observe_transport_cancellation(state: str, cause: str) -> SemanticObservation:
+    try:
+        event = _CANCELLATION_CAUSE_EVENTS[cause]
+    except KeyError as exc:
+        raise ProtocolError(f"unsupported transport cancellation cause: {cause!r}") from exc
+    return enforce_semantic_transition(
+        "cancellation",
+        state,
+        event,
+        detail=f"transport:{cause}",
+    )
+
+
+def observe_channel_lifecycle(
+    state: str,
+    cause: str,
+    *,
+    direction: str | None = None,
+) -> SemanticObservation:
+    event = _channel_event_for_cause(cause, direction=direction)
+    return enforce_semantic_transition(
+        "channel_lifecycle",
+        state,
+        event,
+        detail=_channel_detail(cause, direction),
+    )
+
+
+def channel_lifecycle_capabilities(state: str) -> dict[str, bool]:
+    effects = _channel_capability_effects()
+    try:
+        return dict(effects[state])
+    except KeyError as exc:
+        raise ProtocolError(f"unknown channel lifecycle state: {state!r}") from exc
+
+
+def require_channel_readable(state: str) -> None:
+    if not channel_lifecycle_capabilities(state)["can_read"]:
+        raise ProtocolError(f"channel is not readable in lifecycle state {state!r}")
+
+
+def require_channel_writable(state: str) -> None:
+    if not channel_lifecycle_capabilities(state)["can_write"]:
+        raise ProtocolError(f"channel is not writable in lifecycle state {state!r}")
+
+
+def _single_event(domain: str, flags: Mapping[str, bool]) -> str:
+    events = [event for event, active in flags.items() if active]
+    if len(events) != 1:
+        raise ProtocolError(f"{domain} observation must select exactly one semantic event")
+    return events[0]
+
+
+def _semantic_transition_target(domain: str, state: str, event: str) -> str:
+    if _contract_transition_target is not None and _contract_validate_transition is not None:
+        try:
+            if _contract_validate_transition(domain, state, event):
+                return str(_contract_transition_target(domain, state, event))
+        except Exception:
+            pass
+    try:
+        return _FALLBACK_TRANSITIONS[(domain, state, event)]
+    except KeyError as exc:
+        raise ProtocolError(f"illegal semantic transition for {domain}: {state} + {event}") from exc
+
+
+def _channel_event_for_cause(cause: str, *, direction: str | None) -> str:
+    if cause in _DIRECTIONAL_RESET_EVENTS or cause in _DIRECTIONAL_STOP_EVENTS:
+        if direction in {"inbound", "read", "remote"}:
+            return "channel.read_closed"
+        if direction in {"outbound", "write", "local"}:
+            return "channel.write_closed"
+        raise ProtocolError(f"{cause} requires inbound/read or outbound/write direction")
+    try:
+        return _CHANNEL_CAUSE_EVENTS[cause]
+    except KeyError as exc:
+        raise ProtocolError(f"unsupported channel lifecycle cause: {cause!r}") from exc
+
+
+def _channel_detail(cause: str, direction: str | None) -> str:
+    if direction is None:
+        return f"transport:{cause}"
+    return f"transport:{cause}:{direction}"
+
+
+def _channel_capability_effects() -> Mapping[str, Mapping[str, bool]]:
+    if _contract_semantic_domain is not None:
+        try:
+            effects = _contract_semantic_domain("channel_lifecycle").get("capability_effects", {})
+            if effects:
+                return effects
+        except Exception:
+            pass
+    return _FALLBACK_CHANNEL_CAPABILITIES
+
+
+__all__ = [
+    "SemanticObservation",
+    "channel_lifecycle_capabilities",
+    "enforce_semantic_transition",
+    "observe_backpressure",
+    "observe_channel_lifecycle",
+    "observe_completion",
+    "observe_disconnect",
+    "observe_transport_cancellation",
+    "require_channel_readable",
+    "require_channel_writable",
+]

{tigrcorn_contract-0.3.16.dev12 → tigrcorn_contract-0.3.17.dev1}/src/tigrcorn_contract.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrcorn-contract
-Version: 0.3.16.dev12
+Version: 0.3.17.dev1
 Summary: tigr-asgi-contract adapters and runtime-boundary classification for Tigrcorn ASGI3, WebSocket, and WebTransport surfaces.
 Author-email: Jacob Stewart <jacob@swarmauri.com>
 License: Apache License
@@ -186,8 +186,8 @@ Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: tigrcorn-core==0.3.16.dev12
-Requires-Dist: tigrcorn-asgi==0.3.16.dev12
+Requires-Dist: tigrcorn-core==0.3.17.dev1
+Requires-Dist: tigrcorn-asgi==0.3.17.dev1
 Requires-Dist: tigr-asgi-contract>=0.3.2
 Dynamic: license-file
 

{tigrcorn_contract-0.3.16.dev12 → tigrcorn_contract-0.3.17.dev1}/src/tigrcorn_contract.egg-info/SOURCES.txt

@@ -8,7 +8,9 @@ src/tigrcorn_contract/events.py
 src/tigrcorn_contract/metadata.py
 src/tigrcorn_contract/projection.py
 src/tigrcorn_contract/py.typed
+src/tigrcorn_contract/registry.py
 src/tigrcorn_contract/scopes.py
+src/tigrcorn_contract/semantics.py
 src/tigrcorn_contract.egg-info/PKG-INFO
 src/tigrcorn_contract.egg-info/SOURCES.txt
 src/tigrcorn_contract.egg-info/dependency_links.txt

tigrcorn_contract-0.3.17.dev1/src/tigrcorn_contract.egg-info/requires.txt

@@ -0,0 +1,3 @@
+tigrcorn-core==0.3.17.dev1
+tigrcorn-asgi==0.3.17.dev1
+tigr-asgi-contract>=0.3.2

tigrcorn_contract-0.3.16.dev12/src/tigrcorn_contract.egg-info/requires.txt

@@ -1,3 +0,0 @@
-tigrcorn-core==0.3.16.dev12
-tigrcorn-asgi==0.3.16.dev12
-tigr-asgi-contract>=0.3.2