sqlbuild 0.90.5__tar.gz → 0.91.1__tar.gz

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/Cargo.lock

@@ -597,7 +597,7 @@ checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
 [[package]]
 name = "sqlbuild-kata-native"
-version = "0.90.5"
+version = "0.91.1"
 dependencies = [
  "fensu-policy",
  "globset",

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlbuild
-Version: 0.90.5
+Version: 0.91.1
 Requires-Dist: duckdb>=1.3.2
 Requires-Dist: filelock>=3.20.3
 Requires-Dist: polyglot-sql==0.9.2

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/crates/sqlbuild-kata-native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sqlbuild-kata-native"
-version = "0.90.5"
+version = "0.91.1"
 edition.workspace = true
 license.workspace = true
 publish.workspace = true

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlbuild"
-version = "0.90.5"
+version = "0.91.1"
 description = "Typed, test-first SQL pipelines with local E2E testing"
 readme = "README.md"
 requires-python = ">=3.12"

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/cli/commands/main/entrypoint/entry.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import argparse
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 
 from sqlbuild.cli.commands._helpers.entry.dispatch_errors import dispatch_and_handle_errors
 from sqlbuild.cli.commands._helpers.entry.errors import cli_error_use_color
@@ -19,8 +19,12 @@ from sqlbuild.cli.commands.models import (
     ParsedCliInvocation,
 )
 from sqlbuild.diagnostics.main.diagnostics_context import diagnostics_context
-from sqlbuild.observability import invocation_scope
+from sqlbuild.observability import invocation_external_context_scope, invocation_scope
 from sqlbuild.presentation.main.supports_color import supports_color
+from sqlbuild.runtime.output_capture.exceptions import OutputCaptureInputError
+from sqlbuild.runtime.output_capture.main.invocation_context import (
+    invocation_context_from_environment,
+)
 
 
 def main(argv: Sequence[str] | None = None) -> int:
@@ -36,7 +40,14 @@ def _main_with_dependencies(
 ) -> int:
     """Run the CLI entrypoint with injected handlers for testing."""
 
-    with invocation_scope() as identity:
+    try:
+        external_context: Mapping[str, object] = invocation_context_from_environment()
+    except OutputCaptureInputError:
+        external_context = {}
+    with (
+        invocation_scope() as identity,
+        invocation_external_context_scope(external_context=external_context),
+    ):
         with diagnostics_context(sqlbuild_invocation_id=identity.invocation_id):
             use_color: bool = cli_error_use_color(argv=argv, supports_color=supports_color)
             parser: argparse.ArgumentParser = build_cli_parser(use_color=use_color)

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/compiler/compile/_helpers/analysis/columns.py

@@ -164,6 +164,9 @@ from sqlbuild.compiler.sql_analysis.constants import (
 from sqlbuild.compiler.sql_analysis.constants import (
     POLYGLOT_KIND_TABLE as _POLYGLOT_KIND_TABLE,
 )
+from sqlbuild.compiler.sql_analysis.constants import (
+    POLYGLOT_KIND_TIMESTAMP as _POLYGLOT_KIND_TIMESTAMP,
+)
 from sqlbuild.compiler.sql_analysis.constants import (
     POLYGLOT_KIND_TRY_CAST as _POLYGLOT_KIND_TRY_CAST,
 )
@@ -206,12 +209,18 @@ from sqlbuild.compiler.sql_analysis.constants import (
 from sqlbuild.compiler.sql_analysis.constants import (
     POLYGLOT_PAYLOAD_THIS as _POLYGLOT_PAYLOAD_THIS,
 )
+from sqlbuild.compiler.sql_analysis.constants import (
+    POLYGLOT_PAYLOAD_TIMEZONE as _POLYGLOT_PAYLOAD_TIMEZONE,
+)
 from sqlbuild.compiler.sql_analysis.constants import (
     POLYGLOT_PAYLOAD_TO as _POLYGLOT_PAYLOAD_TO,
 )
 from sqlbuild.compiler.sql_analysis.constants import (
     POLYGLOT_SET_OPERATION_KINDS as _POLYGLOT_SET_OPERATION_KINDS,
 )
+from sqlbuild.compiler.sql_analysis.constants import (
+    TIMESTAMP_WITH_TIME_ZONE_SQL_TYPE_NAME as _TIMESTAMP_WITH_TIME_ZONE_SQL_TYPE_NAME,
+)
 from sqlbuild.compiler.sql_analysis.main._find_matching_paren import find_matching_paren
 from sqlbuild.compiler.sql_analysis.main._schema_validation import get_schema_validations
 from sqlbuild.compiler.sql_analysis.main.import_polyglot_sql import import_polyglot_sql
@@ -1127,6 +1136,11 @@ def _polyglot_expression_type(
         custom_name: object = target.get(_POLYGLOT_PAYLOAD_NAME)
         if isinstance(custom_name, str) and custom_name:
             return custom_name.upper()
+    if (
+        raw_type.lower() == _POLYGLOT_KIND_TIMESTAMP
+        and target.get(_POLYGLOT_PAYLOAD_TIMEZONE) is True
+    ):
+        return _TIMESTAMP_WITH_TIME_ZONE_SQL_TYPE_NAME
     type_name: str = _polyglot_type_name(raw_type)
     precision: object = target.get(_POLYGLOT_PAYLOAD_PRECISION)
     scale: object = target.get(_POLYGLOT_PAYLOAD_SCALE)

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/compiler/sql_analysis/constants.py

@@ -26,6 +26,7 @@ POLYGLOT_KIND_SELECT: str = "select"
 POLYGLOT_KIND_STRING_AGG: str = "string_agg"
 POLYGLOT_KIND_SUM: str = "sum"
 POLYGLOT_KIND_TABLE: str = "table"
+POLYGLOT_KIND_TIMESTAMP: str = "timestamp"
 POLYGLOT_KIND_TRY_CAST: str = "try_cast"
 POLYGLOT_KIND_UNION: str = "union"
 POLYGLOT_SET_OPERATION_KINDS: frozenset[str] = frozenset(
@@ -56,7 +57,9 @@ POLYGLOT_PAYLOAD_SCALE: str = "scale"
 POLYGLOT_PAYLOAD_SELECT: str = "select"
 POLYGLOT_PAYLOAD_TABLE: str = "table"
 POLYGLOT_PAYLOAD_THIS: str = "this"
+POLYGLOT_PAYLOAD_TIMEZONE: str = "timezone"
 POLYGLOT_PAYLOAD_TO: str = "to"
+TIMESTAMP_WITH_TIME_ZONE_SQL_TYPE_NAME: str = "TIMESTAMPTZ"
 POLYGLOT_JOIN_FULL: str = "FULL"
 POLYGLOT_JOIN_LEFT: str = "LEFT"
 POLYGLOT_JOIN_RIGHT: str = "RIGHT"

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/integrations/dagster/_helpers/invocation_context.py

@@ -13,13 +13,13 @@ def dagster_invocation_context(context: Any) -> dict[str, object]:
     """Return bounded, non-sensitive identifiers for subprocess correlation."""
 
     integration: dict[str, object] = {"name": "dagster"}
-    run_id: str | None = _string_attribute(source=context, name="run_id")
+    run_id: str | None = _run_id(context=context)
     if run_id is not None:
         integration["run_id"] = run_id
     job_name: str | None = _string_attribute(source=context, name="job_name")
     if job_name is not None:
         integration["job_name"] = job_name
-    retry_number: int | None = _integer_attribute(source=context, name="retry_number")
+    retry_number: int | None = _retry_number(context=context)
     if retry_number is not None:
         integration["retry_number"] = retry_number
     step_key: str | None = _step_key(context=context)
@@ -37,7 +37,10 @@ def _step_key(*, context: Any) -> str | None:
     bounded_direct: str | None = _bounded_identifier(direct)
     if bounded_direct is not None:
         return bounded_direct
-    handle: object | None = _attribute(source=context, name="op_handle")
+    operation_context: object | None = _attribute(source=context, name="op_execution_context")
+    handle: object | None = _attribute(source=operation_context, name="op_handle")
+    if handle is None:
+        handle = _attribute(source=context, name="op_handle")
     formatter: object | None = _attribute(source=handle, name="to_string")
     if callable(formatter):
         value: object = cast(Callable[[], object], formatter)()
@@ -45,6 +48,18 @@ def _step_key(*, context: Any) -> str | None:
     return None
 
 
+def _run_id(*, context: Any) -> str | None:
+    run: object | None = _attribute(source=context, name="run")
+    nested: str | None = _string_attribute(source=run, name="run_id")
+    return nested if nested is not None else _string_attribute(source=context, name="run_id")
+
+
+def _retry_number(*, context: Any) -> int | None:
+    operation_context: object | None = _attribute(source=context, name="op_execution_context")
+    nested: int | None = _integer_attribute(source=operation_context, name="retry_number")
+    return nested if nested is not None else _integer_attribute(source=context, name="retry_number")
+
+
 def _string_attribute(*, source: Any, name: str) -> str | None:
     return _bounded_identifier(_attribute(source=source, name=name))
 

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/observability.py

@@ -37,6 +37,9 @@ from sqlbuild.runtime.observability.main.execution_identity_to_dict import (
     execution_identity_to_dict as _execution_identity_to_dict,
 )
 from sqlbuild.runtime.observability.main.identity_scope import identity_scope as _identity_scope
+from sqlbuild.runtime.observability.main.invocation_external_context_scope import (
+    invocation_external_context_scope as _invocation_external_context_scope,
+)
 from sqlbuild.runtime.observability.main.invocation_scope import (
     invocation_scope as _invocation_scope,
 )
@@ -103,6 +106,7 @@ __all__ = (
     "current_execution_identity",
     "execution_identity_to_dict",
     "identity_scope",
+    "invocation_external_context_scope",
     "invocation_scope",
     "is_terminal_event",
     "lifecycle_event_from_json",
@@ -179,6 +183,16 @@ def invocation_scope(invocation_id: str | None = None) -> Iterator[ExecutionIden
         yield identity
 
 
+@contextmanager
+def invocation_external_context_scope(
+    *, external_context: Mapping[str, object]
+) -> Iterator[Mapping[str, JSONValue]]:
+    """Attach validated integration context to lifecycle facts in the current invocation."""
+
+    with _invocation_external_context_scope(external_context=external_context) as installed:
+        yield installed
+
+
 @contextmanager
 def run_scope(run_id: str) -> Iterator[ExecutionIdentity]:
     """Install a run while preserving or creating its invocation identity."""

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/runtime/observability/_helpers/factory.py

@@ -6,7 +6,10 @@ from importlib.metadata import version
 from types import MappingProxyType
 from uuid import uuid4
 
-from sqlbuild.runtime.observability._helpers.identity import current_execution_identity
+from sqlbuild.runtime.observability._helpers.identity import (
+    current_execution_identity,
+    current_invocation_external_context,
+)
 from sqlbuild.runtime.observability.constants import CURRENT_LIFECYCLE_EVENT_SCHEMA_VERSION
 from sqlbuild.runtime.observability.exceptions import ObservabilityValidationError
 from sqlbuild.runtime.observability.models import ExecutionIdentity, LifecycleEvent
@@ -43,10 +46,12 @@ def create_lifecycle_event(
         ),
         occurred_at=datetime.now(UTC) if occurred_at is None else occurred_at,
         invocation_id=identity.invocation_id,
+        invocation_sequence=0,
         run_id=identity.run_id,
         resource_id=identity.resource_id,
         resource_attempt_id=identity.resource_attempt_id,
         operation_id=identity.operation_id,
         statement_id=identity.statement_id,
+        external_context=current_invocation_external_context(),
         payload=payload,
     )

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/runtime/observability/_helpers/identity.py

@@ -2,31 +2,40 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterator
+from collections.abc import Iterator, Mapping
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from dataclasses import asdict, replace
+from types import MappingProxyType
+from typing import cast
 from uuid import uuid4
 
+from sqlbuild.runtime.observability._helpers.validation import freeze_json
 from sqlbuild.runtime.observability.exceptions import ObservabilityValidationError
 from sqlbuild.runtime.observability.models import ExecutionIdentity
+from sqlbuild.runtime.observability.types import JSONValue
 
 _CURRENT_EXECUTION_IDENTITY: ContextVar[ExecutionIdentity | None] = ContextVar(
     "sqlbuild_execution_identity", default=None
 )
 
 
+_CURRENT_INVOCATION_EXTERNAL_CONTEXT: ContextVar[Mapping[str, JSONValue]] = ContextVar(
+    "sqlbuild_invocation_external_context", default=MappingProxyType({})
+)
+
+
 def current_execution_identity() -> ExecutionIdentity | None:
     return _CURRENT_EXECUTION_IDENTITY.get()
 
 
 @contextmanager
 def identity_scope(identity: ExecutionIdentity) -> Iterator[ExecutionIdentity]:
-    token: Token[ExecutionIdentity | None] = _CURRENT_EXECUTION_IDENTITY.set(identity)
+    identity_token: Token[ExecutionIdentity | None] = _CURRENT_EXECUTION_IDENTITY.set(identity)
     try:
         yield identity
     finally:
-        _CURRENT_EXECUTION_IDENTITY.reset(token)
+        _CURRENT_EXECUTION_IDENTITY.reset(identity_token)
 
 
 def execution_identity_to_dict(identity: ExecutionIdentity) -> dict[str, str | None]:
@@ -49,6 +58,29 @@ def invocation_scope(invocation_id: str | None = None) -> Iterator[ExecutionIden
         yield installed
 
 
+def current_invocation_external_context() -> Mapping[str, JSONValue]:
+    """Return validated external context for the active invocation."""
+
+    return _CURRENT_INVOCATION_EXTERNAL_CONTEXT.get()
+
+
+@contextmanager
+def invocation_external_context_scope(
+    *, external_context: Mapping[str, object]
+) -> Iterator[Mapping[str, JSONValue]]:
+    """Install validated integration context for lifecycle facts in one command."""
+
+    frozen: JSONValue = freeze_json(value=external_context, path="external_context")
+    if not isinstance(frozen, Mapping):
+        raise ObservabilityValidationError("external_context must be a JSON object")
+    context: Mapping[str, JSONValue] = cast(Mapping[str, JSONValue], frozen)
+    token: Token[Mapping[str, JSONValue]] = _CURRENT_INVOCATION_EXTERNAL_CONTEXT.set(context)
+    try:
+        yield context
+    finally:
+        _CURRENT_INVOCATION_EXTERNAL_CONTEXT.reset(token)
+
+
 @contextmanager
 def run_scope(run_id: str) -> Iterator[ExecutionIdentity]:
     current: ExecutionIdentity | None = current_execution_identity()

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/runtime/observability/_helpers/observability.py

@@ -11,8 +11,9 @@ from sqlbuild.runtime.observability._helpers.validation import validate_schema_v
 from sqlbuild.runtime.observability.constants import (
     CURRENT_DIAGNOSTIC_LOG_SCHEMA_VERSION,
     DIAGNOSTIC_ENVELOPE_FIELDS,
-    LIFECYCLE_ENVELOPE_FIELDS,
+    LIFECYCLE_ENVELOPE_FIELDS_BY_VERSION,
     LIFECYCLE_EVENT_CATALOGS,
+    LIFECYCLE_INVOCATION_METADATA_SCHEMA_VERSION,
 )
 from sqlbuild.runtime.observability.exceptions import ObservabilityValidationError
 from sqlbuild.runtime.observability.models import (
@@ -68,27 +69,29 @@ def lifecycle_event_to_json(event: LifecycleEvent | OpaqueLifecycleEvent) -> str
 
     if isinstance(event, OpaqueLifecycleEvent):
         return _dumps(_json_data(event.raw))
-    return _dumps(
-        {
-            "event_id": event.event_id,
-            "event_type": event.event_type,
-            "schema_version": event.schema_version,
-            "producer": event.producer,
-            "producer_version": event.producer_version,
-            "occurred_at": _timestamp(event.occurred_at),
-            "invocation_id": event.invocation_id,
-            "run_id": event.run_id,
-            "resource_id": event.resource_id,
-            "resource_attempt_id": event.resource_attempt_id,
-            "operation_id": event.operation_id,
-            "statement_id": event.statement_id,
-            "payload": _json_data(event.payload),
-        }
-    )
+    data: dict[str, object] = {
+        "event_id": event.event_id,
+        "event_type": event.event_type,
+        "schema_version": event.schema_version,
+        "producer": event.producer,
+        "producer_version": event.producer_version,
+        "occurred_at": _timestamp(event.occurred_at),
+        "invocation_id": event.invocation_id,
+        "run_id": event.run_id,
+        "resource_id": event.resource_id,
+        "resource_attempt_id": event.resource_attempt_id,
+        "operation_id": event.operation_id,
+        "statement_id": event.statement_id,
+        "payload": _json_data(event.payload),
+    }
+    if event.schema_version >= LIFECYCLE_INVOCATION_METADATA_SCHEMA_VERSION:
+        data["invocation_sequence"] = event.invocation_sequence
+        data["external_context"] = _json_data(event.external_context)
+    return _dumps(data)
 
 
 def lifecycle_event_from_json(raw_json: str) -> LifecycleEvent | OpaqueLifecycleEvent:
-    """Decode known v1 events strictly and retain unknown envelopes opaquely."""
+    """Decode known events strictly and retain unknown envelopes opaquely."""
 
     data: dict[str, Any] = _loads_object(raw_json=raw_json, envelope_name="lifecycle event")
     event_type: object = data.get("event_type")
@@ -106,7 +109,7 @@ def lifecycle_event_from_json(raw_json: str) -> LifecycleEvent | OpaqueLifecycle
         return OpaqueLifecycleEvent(raw=data)
     _reject_unknown_fields(
         data=data,
-        allowed=LIFECYCLE_ENVELOPE_FIELDS,
+        allowed=LIFECYCLE_ENVELOPE_FIELDS_BY_VERSION[schema_version],
         envelope_name=f"v{schema_version} lifecycle event",
     )
     try:
@@ -122,11 +125,13 @@ def lifecycle_event_from_json(raw_json: str) -> LifecycleEvent | OpaqueLifecycle
             producer_version=data["producer_version"],
             occurred_at=occurred_at,
             invocation_id=data["invocation_id"],
+            invocation_sequence=data.get("invocation_sequence"),
             run_id=data.get("run_id"),
             resource_id=data.get("resource_id"),
             resource_attempt_id=data.get("resource_attempt_id"),
             operation_id=data.get("operation_id"),
             statement_id=data.get("statement_id"),
+            external_context=data.get("external_context", {}),
             payload=data.get("payload", {}),
         )
     except KeyError as error:

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/runtime/observability/classes/event_dispatcher.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from collections import deque
 from contextvars import ContextVar, Token
+from dataclasses import replace
 from functools import partial
 from threading import RLock
 from typing import Literal, cast, overload
@@ -14,6 +15,9 @@ from sqlbuild.runtime.observability._helpers.failure_formatting import (
     _safe_subscriber_name,
 )
 from sqlbuild.runtime.observability._helpers.validation import validate_known_lifecycle_event
+from sqlbuild.runtime.observability.constants import (
+    LIFECYCLE_INVOCATION_METADATA_SCHEMA_VERSION,
+)
 from sqlbuild.runtime.observability.exceptions import ObservabilityValidationError
 from sqlbuild.runtime.observability.models import (
     DiagnosticLog,
@@ -47,6 +51,7 @@ class EventDispatcher:
         self._publication_lock: RLock = RLock()
         self._lifecycle: tuple[LifecycleRegistration, ...] = ()
         self._diagnostics: tuple[DiagnosticRegistration, ...] = ()
+        self._lifecycle_sequences: dict[str, int] = {}
         self._pending_publications: deque[
             tuple[Literal["lifecycle"], LifecycleEvent | OpaqueLifecycleEvent, bool]
             | tuple[Literal["diagnostic"], DiagnosticLog, bool]
@@ -118,6 +123,14 @@ class EventDispatcher:
                 lifecycle_value: LifecycleEvent | OpaqueLifecycleEvent = cast(
                     LifecycleEvent | OpaqueLifecycleEvent, value
                 )
+                if (
+                    isinstance(lifecycle_value, LifecycleEvent)
+                    and lifecycle_value.schema_version
+                    >= LIFECYCLE_INVOCATION_METADATA_SCHEMA_VERSION
+                ):
+                    sequence: int = self._lifecycle_sequences.get(lifecycle_value.invocation_id, 0)
+                    self._lifecycle_sequences[lifecycle_value.invocation_id] = sequence + 1
+                    lifecycle_value = replace(lifecycle_value, invocation_sequence=sequence)
                 self._pending_publications.append((channel, lifecycle_value, suppress_health))
             else:
                 diagnostic_value: DiagnosticLog = cast(DiagnosticLog, value)

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/runtime/observability/constants.py

@@ -5,7 +5,8 @@ from types import MappingProxyType
 
 from sqlbuild.runtime.observability.models import LifecycleEventDefinition
 
-CURRENT_LIFECYCLE_EVENT_SCHEMA_VERSION: int = 1
+CURRENT_LIFECYCLE_EVENT_SCHEMA_VERSION: int = 2
+LIFECYCLE_INVOCATION_METADATA_SCHEMA_VERSION: int = 2
 CURRENT_DIAGNOSTIC_LOG_SCHEMA_VERSION: int = 1
 DURATION_MS_FIELD: str = "duration_ms"
 EXIT_CODE_FIELD: str = "exit_code"
@@ -296,7 +297,7 @@ FORBIDDEN_STATEMENT_PAYLOAD_FIELDS: frozenset[str] = frozenset(
         "statement_sql",
     }
 )
-LIFECYCLE_ENVELOPE_FIELDS: frozenset[str] = frozenset(
+LIFECYCLE_ENVELOPE_FIELDS_V1: frozenset[str] = frozenset(
     {
         "event_id",
         "event_type",
@@ -313,6 +314,12 @@ LIFECYCLE_ENVELOPE_FIELDS: frozenset[str] = frozenset(
         "payload",
     }
 )
+LIFECYCLE_ENVELOPE_FIELDS_V2: frozenset[str] = LIFECYCLE_ENVELOPE_FIELDS_V1 | frozenset(
+    {"invocation_sequence", "external_context"}
+)
+LIFECYCLE_ENVELOPE_FIELDS_BY_VERSION: Mapping[int, frozenset[str]] = MappingProxyType(
+    {1: LIFECYCLE_ENVELOPE_FIELDS_V1, 2: LIFECYCLE_ENVELOPE_FIELDS_V2}
+)
 DIAGNOSTIC_ENVELOPE_FIELDS: frozenset[str] = frozenset(
     {
         "schema_version",
@@ -517,6 +524,6 @@ LIFECYCLE_EVENT_CATALOG_V1: Mapping[str, LifecycleEventDefinition] = MappingProx
     }
 )
 LIFECYCLE_EVENT_CATALOGS: Mapping[int, Mapping[str, LifecycleEventDefinition]] = MappingProxyType(
-    {CURRENT_LIFECYCLE_EVENT_SCHEMA_VERSION: LIFECYCLE_EVENT_CATALOG_V1}
+    {1: LIFECYCLE_EVENT_CATALOG_V1, 2: LIFECYCLE_EVENT_CATALOG_V1}
 )
 LIFECYCLE_EVENT_CATALOG: Mapping[str, LifecycleEventDefinition] = LIFECYCLE_EVENT_CATALOG_V1

sqlbuild-0.91.1/src/sqlbuild/runtime/observability/main/invocation_external_context_scope.py

@@ -0,0 +1,19 @@
+"""Invocation lifecycle metadata scope entrypoint."""
+
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+
+from sqlbuild.runtime.observability._helpers.identity import (
+    invocation_external_context_scope as _invocation_external_context_scope,
+)
+from sqlbuild.runtime.observability.types import JSONValue
+
+
+@contextmanager
+def invocation_external_context_scope(
+    *, external_context: Mapping[str, object]
+) -> Iterator[Mapping[str, JSONValue]]:
+    """Install validated integration context for lifecycle event creation."""
+
+    with _invocation_external_context_scope(external_context=external_context) as installed:
+        yield installed

{sqlbuild-0.90.5 → sqlbuild-0.91.1}/src/sqlbuild/runtime/observability/models.py

@@ -86,11 +86,13 @@ class LifecycleEvent:
     producer_version: str
     occurred_at: datetime
     invocation_id: str
+    invocation_sequence: int | None = None
     run_id: str | None = None
     resource_id: str | None = None
     resource_attempt_id: str | None = None
     operation_id: str | None = None
     statement_id: str | None = None
+    external_context: Mapping[str, JSONValue] = field(default_factory=dict)
     payload: Mapping[str, JSONValue] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
@@ -102,7 +104,10 @@ class LifecycleEvent:
             validate_schema_version,
             validate_timestamp,
         )
-        from sqlbuild.runtime.observability.constants import CURRENT_LIFECYCLE_EVENT_SCHEMA_VERSION
+        from sqlbuild.runtime.observability.constants import (
+            CURRENT_LIFECYCLE_EVENT_SCHEMA_VERSION,
+            LIFECYCLE_EVENT_CATALOGS,
+        )
 
         for field_name in (
             "event_id",
@@ -113,11 +118,24 @@ class LifecycleEvent:
         ):
             validate_required_text(value=getattr(self, field_name), field_name=field_name)
         validate_schema_version(value=self.schema_version)
-        if self.schema_version != CURRENT_LIFECYCLE_EVENT_SCHEMA_VERSION:
+        if self.schema_version not in LIFECYCLE_EVENT_CATALOGS:
+            raise ObservabilityValidationError(
+                "LifecycleEvent only represents known schema versions through "
+                f"{CURRENT_LIFECYCLE_EVENT_SCHEMA_VERSION}; decode other versions as "
+                "OpaqueLifecycleEvent"
+            )
+        if self.schema_version == 1:
+            if self.invocation_sequence is not None or self.external_context:
+                raise ObservabilityValidationError(
+                    "schema version 1 lifecycle events cannot contain invocation metadata"
+                )
+        elif (
+            isinstance(self.invocation_sequence, bool)
+            or not isinstance(self.invocation_sequence, int)
+            or self.invocation_sequence < 0
+        ):
             raise ObservabilityValidationError(
-                "LifecycleEvent only represents known schema version "
-                f"{CURRENT_LIFECYCLE_EVENT_SCHEMA_VERSION}; "
-                "decode other versions as OpaqueLifecycleEvent"
+                "invocation_sequence must be a non-negative integer excluding bool"
             )
         validate_timestamp(value=self.occurred_at)
         for field_name in (
@@ -128,6 +146,12 @@ class LifecycleEvent:
             "statement_id",
         ):
             validate_optional_text(value=getattr(self, field_name), field_name=field_name)
+        frozen_context: JSONValue = freeze_json(
+            value=self.external_context, path="external_context"
+        )
+        if not isinstance(frozen_context, Mapping):
+            raise ObservabilityValidationError("external_context must be a JSON object")
+        object.__setattr__(self, "external_context", frozen_context)
         frozen_payload: JSONValue = freeze_json(value=self.payload, path="payload")
         if not isinstance(frozen_payload, Mapping):
             raise ObservabilityValidationError("payload must be a JSON object")