Docs: Align execution observations with SQLMesh documentation conventions

Signed-off-by: mday-io <mdaytn@gmail.com>

Author: mday-io

docs/reference/execution_observations.md

@@ -7,11 +7,13 @@ transactions, or `Console` progress reporting.
 ## Console observer registration
 
 `Console.get_execution_observer()` returns `None` by default. A `Console`
-subclass can return an `Observer` callback from
-`sqlmesh.core.execution_observation`. The callback receives a phase, a read-only
-mapping of facts, and the original exception or `None`.
+subclass can return an `Observer` callback from `sqlmesh.core.execution_observation`.
+The callback receives a
+phase, a read-only mapping of facts, and the original exception or `None`.
+For general Python integration details, see the [Python API reference](./python.md).
 
-This console prints the kind, action, and finish error for each observed operation:
+The following console prints the kind, action, and finish error for each observed
+operation. The example uses `examples/sushi` relative to the SQLMesh repository root:
 
 ```python
 from typing import Any, Literal, Mapping, Optional
@@ -22,38 +24,36 @@ from sqlmesh.core.execution_observation import Observer
 
 
 def observe(
-	phase: Literal["start", "finish"],
-	facts: Mapping[str, Any],
-	error: Optional[BaseException],
+    phase: Literal["start", "finish"],
+    facts: Mapping[str, Any],
+    error: Optional[BaseException],
 ) -> None:
-	if phase == "finish":
-		print(f"{facts['kind']}/{facts['action']}: error={error!r}")
+    if phase == "finish":
+        print(f"{facts['kind']}/{facts['action']}: error={error!r}")
 
 
 class ObservedConsole(TerminalConsole):
-	def get_execution_observer(self) -> Optional[Observer]:
-		return observe
+    def get_execution_observer(self) -> Optional[Observer]:
+        return observe
 
 
 set_console(ObservedConsole())
 context = Context(paths=["examples/sushi"])
 ```
 
-A `Context` captures the console returned by `get_console()` when the context is
-constructed. `BuiltInPlanEvaluator.evaluate()` and
-`Scheduler.run_merged_intervals()` enter `console_observer_scope()` for their
-observed work. Unless an `observer_scope()` is already active,
-`console_observer_scope()` calls `get_execution_observer()` once. Nested calls
-reuse the observer already active in the scope. If `get_execution_observer()`
-raises an ordinary `Exception`, SQLMesh disables observation for that scope and
+A `Context` uses the `Console` that was current when the context was created.
+Unless an explicit `observer_scope()` is active, SQLMesh resolves
+`get_execution_observer()` once for each outer plan evaluation or scheduler run.
+Nested calls reuse that observer. If the getter raises an ordinary `Exception`,
+SQLMesh disables observation for that plan evaluation or scheduler run and
 continues native work.
 
 ## Observer scopes
 
 `observer_scope(observer)` from `sqlmesh.core.execution_observation` sets the
-active observer for the scope. A nested scope restores the previously active
-observer when it exits. `observer_scope(None)` disables observation for that
-scope, including automatic Console registration.
+observer for the duration of the scope. A nested scope restores the previously
+active observer when it exits. `observer_scope(None)` disables observation inside
+that scope, including automatic Console registration.
 
 ## Callback lifecycle
 
@@ -79,13 +79,13 @@ is not an `Exception`, the work and `finish` callback do not run. If `finish`
 raises a `BaseException` that is not an `Exception`, that failure can replace
 the workload error.
 
-A worker's `BaseException` can reach the caller after SQLMesh waits for its
-workers. A DAG run that records a terminal error stops scheduling nodes and
-raises that error after its running workers exit. In parallel execution,
-`concurrent_apply_to_values()` stores a worker's `BaseException` in a future and
-waits for the pool to finish before reading results. Blocking callbacks and
-process termination are outside the observer failure guarantee. SQLMesh does
-not log observer failures.
+If a worker raises a `BaseException`, the error can reach the caller after its
+worker pool exits. If a DAG run records a terminal error, SQLMesh stops
+scheduling nodes and waits for running workers to exit before it raises that
+error. Parallel value operations also wait for their workers to finish before
+raising a worker's `BaseException`. Blocking callbacks and process termination
+are outside the observer failure guarantee. SQLMesh does not log observer
+failures.
 
 Nested workload calls produce nested observations. Callbacks for concurrent
 workers can interleave, and SQLMesh provides no global callback order. Observers
@@ -112,18 +112,21 @@ observed operation and can be absent when work exits early or fails.
 | `audit` | `audit` | `audit_name`; `audit_result` at finish if produced |
 | `query` | `execute` | `engine` dialect string |
 
-`Snapshot` and `AuditResult` values are borrowed native objects. Consumers must
+[`Snapshot`](../concepts/architecture/snapshots.md) and `AuditResult` values are
+borrowed native objects. Consumers must
 treat these objects and other nested values as read-only and must not retain them
 beyond the matching `finish` callback. The mapping's read-only wrapper does not
 freeze nested objects. Facts are not a JSON event schema. SQLMesh does not
 interpret audit results as consumer statuses or inherit model facts into child
 mappings. Consumers that need facts after `finish` copy and normalize those
 values during the callback.
 
-SQLMesh calls `finish` for an audit before it runs later audits or publishes WAP
-results. A later audit or publication can still fail. An audit query failure can
-produce a `finish` callback without an `AuditResult`. The physical materialization
-callback ends after its surrounding transaction and session exit.
+SQLMesh calls `finish` for an audit before it runs later audits or completes
+write-audit-publish (WAP). A later audit or WAP publication can still fail. An audit
+query failure can produce a `finish` callback without an `AuditResult`. The
+[audits guide](../concepts/audits.md) describes audit behavior in plans and
+runs. The physical materialization callback ends after its surrounding
+transaction and session exit.
 
 An observed operation can do no work, issue multiple statements, or trigger
 internal driver retries. The observation does not predict how many statements
@@ -143,23 +146,20 @@ use that ordering to associate existing log entries with the invocation.
 
 ## Worker context
 
-Outside callback delivery, an active observer makes
-`execution_context_factory()` return `contextvars.copy_context`.
-`Scheduler.run_merged_intervals()` passes that function to
-`concurrent_apply_to_dag()`. `SnapshotEvaluator` passes it to
-`concurrent_apply_to_snapshots()` and `concurrent_apply_to_values()`. Each node
-or value gets its own context copy, including during serial execution. Successor
-nodes start from the context captured for the DAG run. They do not inherit
-changes made by earlier workers. `ConcurrentDAGExecutor.run()` captures a fresh
-context for each run. Schema creation and data-object listing use
-`concurrent_apply_to_values()`, so each value gets its own context copy.
+When an observer is active outside callback delivery, SQLMesh copies the current
+Python context for each task in scheduler and snapshot DAG work, snapshot schema creation, and
+data-object listing. That context carries Python's [context variables](https://docs.python.org/3/library/contextvars.html).
+Each task gets its own context copy, including during serial execution. DAG
+successors use the context captured for the run. They do not inherit changes
+made by earlier workers. Reusing a DAG executor captures a fresh context for
+each run.
 
 Context copies are shallow. Mutable objects stored in `ContextVar` values remain
 shared across copies. A parent identity stored in a consumer-owned `ContextVar`
-is available to each worker. These copies apply to the scheduler DAG and to the
-`SnapshotEvaluator` calls above. Other SQLMesh concurrency helpers and arbitrary
-consumer threads do not receive these copies.
+is available to each worker. SQLMesh uses these copies in the scheduler and
+snapshot DAG, schema creation, and data-object listing. Arbitrary consumer
+threads and other concurrency helpers do not receive these copies.
 
-With no observer registered, `execution_context_factory()` returns `None`. The
-concurrency helpers retain their existing `ContextVar` behavior for serial and
-worker execution.
+With no observer registered, these operations do not copy contexts. The concurrency
+helpers retain their existing `ContextVar` behavior for serial and worker
+execution.