Select execution observers from context

This commit is contained in:
2026-11-22 18:07:17 +00:00
parent f762c0358e
commit ea7cc170ad
6 changed files with 104 additions and 6 deletions

View File

@@ -21,8 +21,9 @@ Prepared-content notification is a separate opt-in callback, not an event.
The facade masks inherited recorder and prepared-claim state when entering The facade masks inherited recorder and prepared-claim state when entering
preparation or execution. Delegated calls from an injected collaborator retain preparation or execution. Delegated calls from an injected collaborator retain
the caller's cancellation, deadline, and unrelated context values, but do not the caller's cancellation, deadline, and unrelated context values, but do not
reuse the enclosing invocation's accounting. Only the new request's observer reuse the enclosing invocation's accounting. Ordinary runs compose the request
(or the claimed handle's retained observer) enables its observation lifecycle. observer before any observers selected by the invocation context; contextual
selection survives this boundary. Prepared handles use their retained observer.
A recorder keeps only counters, resolved identity fields, and the selected A recorder keeps only counters, resolved identity fields, and the selected
callback. It has no global history, queue, goroutine, or mutex held across a callback. It has no global history, queue, goroutine, or mutex held across a
@@ -53,12 +54,13 @@ attempts above the first in a generation, and repair generations with at least
one dispatch. A terminal event is an aggregate and must not be added to its one dispatch. A terminal event is an aggregate and must not be added to its
attempt events. attempt events.
An execution group is a zero-ready synchronized collector of explicitly selected An execution group is a zero-ready synchronized collector of selected
events. It enrolls by run ID and aggregates each run's first terminal counters and events. It enrolls by run ID and aggregates each run's first terminal counters and
presence-aware usage exactly once. Snapshots copy members and totals under one presence-aware usage exactly once. Snapshots copy members and totals under one
lock; terminal coverage and token completeness are distinct. Observer fan-out lock; terminal coverage and token completeness are distinct. Observer fan-out
copies the callback slice and invokes callbacks synchronously without holding a copies the callback slice and invokes callbacks synchronously without holding a
group lock. No group history, registry, or automatic nested membership exists. group lock. No group history or registry exists; contextual selection can enroll
nested ordinary runs that use the scoped context.
Smoke diagnostics mask inherited execution-recorder state while invoking Smoke diagnostics mask inherited execution-recorder state while invoking
generation or HTTP collaborators. Their private attempt evidence is assembled generation or HTTP collaborators. Their private attempt evidence is assembled

View File

@@ -72,6 +72,8 @@ a release, dependency upgrade, CLI implementation, or changes to published notes
## Stage 1 — Context Helper And Ordinary Run Selection ## Stage 1 — Context Helper And Ordinary Run Selection
**Completed.**
Touch `observations.go`, the root `Engine.Run` in `engine.go`, and context support Touch `observations.go`, the root `Engine.Run` in `engine.go`, and context support
in `internal/observation/recorder.go` or a focused adjacent file. in `internal/observation/recorder.go` or a focused adjacent file.

View File

@@ -605,13 +605,18 @@ func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
scope := usecase.NewOperationScope(ctx, req.OperationTimeout) scope := usecase.NewOperationScope(ctx, req.OperationTimeout)
defer scope.Close() defer scope.Close()
ctx = scope.Context ctx = scope.Context
if req.Observer == nil { var explicit domain.ExecutionObserver
if req.Observer != nil {
explicit = func(event domain.ExecutionEvent) { req.Observer(fromDomainExecutionEvent(event)) }
}
observer := observation.Compose(explicit, observation.ObserverFromContext(ctx))
if observer == nil {
result, err := e.run(ctx, req) result, err := e.run(ctx, req)
err = mapPublicError(scope.Finalize(err)) err = mapPublicError(scope.Finalize(err))
scope.Close() scope.Close()
return result, err return result, err
} }
recorder, idErr := observation.New(func(event domain.ExecutionEvent) { req.Observer(fromDomainExecutionEvent(event)) }) recorder, idErr := observation.New(observer)
if req.ContinueFrom != nil && req.ContinueFrom.internal != nil { if req.ContinueFrom != nil && req.ContinueFrom.internal != nil {
recorder.SetParentRunID(req.ContinueFrom.internal.RunID()) recorder.SetParentRunID(req.ContinueFrom.internal.RunID())
} }

View File

@@ -195,6 +195,22 @@ func (r *Recorder) deliver(event domain.ExecutionEvent) {
type contextKey struct{} type contextKey struct{}
type observerKey struct{}
// WithObserver adds an observer to the inherited contextual selection.
func WithObserver(ctx context.Context, observer domain.ExecutionObserver) context.Context {
if observer == nil {
return ctx
}
return context.WithValue(ctx, observerKey{}, Compose(ObserverFromContext(ctx), observer))
}
// ObserverFromContext returns the contextual observer selection, if any.
func ObserverFromContext(ctx context.Context) domain.ExecutionObserver {
observer, _ := ctx.Value(observerKey{}).(domain.ExecutionObserver)
return observer
}
// WithoutExecutionState starts a public operation without inheriting another // WithoutExecutionState starts a public operation without inheriting another
// invocation's recorder or prepared-claim sink. Other context values and all // invocation's recorder or prepared-claim sink. Other context values and all
// cancellation/deadline behavior remain with the caller's context. // cancellation/deadline behavior remain with the caller's context.

View File

@@ -4,6 +4,7 @@ import (
"context" "context"
"errors" "errors"
"fmt" "fmt"
"reflect"
"testing" "testing"
"time" "time"
@@ -11,6 +12,66 @@ import (
"go.maximumdirect.net/promptkit" "go.maximumdirect.net/promptkit"
) )
func TestContextualObserversSelectIndependentRuns(t *testing.T) {
var order []string
var events []promptkit.ExecutionEvent
observer := func(name string) promptkit.ExecutionObserver {
return func(event promptkit.ExecutionEvent) {
order = append(order, name)
if name == "inherited" {
events = append(events, event)
}
}
}
base := context.Background()
if promptkit.WithExecutionObserver(base, nil) != base {
t.Fatal("nil observer changed context")
}
ctx := promptkit.WithExecutionObserver(base, observer("inherited"))
ctx = promptkit.WithExecutionObserver(ctx, observer("new"))
ctx = promptkit.WithExecutionObserver(ctx, nil)
child := observationEngine(t, observationClientFunc(func(context.Context, promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) {
return &promptkit.GenerateResponse{Content: "child"}, nil
}))
var childResult *promptkit.RunResult
outer := observationEngine(t, observationClientFunc(func(callCtx context.Context, _ promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) {
var err error
childResult, err = child.Run(callCtx, promptkit.RunRequest{PromptID: "prompt", Observer: observer("child explicit")})
return &promptkit.GenerateResponse{Content: "outer"}, err
}))
result, err := outer.Run(ctx, promptkit.RunRequest{PromptID: "prompt", Observer: observer("outer explicit")})
if err != nil {
t.Fatal(err)
}
want := []string{"outer explicit", "inherited", "new", "child explicit", "inherited", "new", "child explicit", "inherited", "new", "child explicit", "inherited", "new", "outer explicit", "inherited", "new", "outer explicit", "inherited", "new"}
if !reflect.DeepEqual(order, want) {
t.Fatalf("observer order = %v", order)
}
if childResult.RunID == "" || result.RunID == "" || childResult.RunID == result.RunID {
t.Fatalf("run IDs: outer=%q child=%q", result.RunID, childResult.RunID)
}
counts := map[string]int{}
for _, event := range events {
counts[event.RunID]++
}
if counts[result.RunID] != 3 || counts[childResult.RunID] != 3 || len(counts) != 2 {
t.Fatalf("events = %+v", events)
}
order = nil
if _, err := child.Run(base, promptkit.RunRequest{PromptID: "prompt"}); err != nil {
t.Fatal(err)
}
if len(order) != 0 {
t.Fatalf("unrelated context selected observer: %v", order)
}
if _, err := child.Run(ctx, promptkit.RunRequest{PromptID: "prompt"}); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(order, []string{"inherited", "new", "inherited", "new", "inherited", "new"}) {
t.Fatalf("context-only observer order = %v", order)
}
}
type observationClientFunc func(context.Context, promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) type observationClientFunc func(context.Context, promptkit.GenerateRequest) (*promptkit.GenerateResponse, error)
func (f observationClientFunc) Generate(ctx context.Context, req promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) { func (f observationClientFunc) Generate(ctx context.Context, req promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) {

View File

@@ -17,6 +17,18 @@ import (
// event, and Promptkit keeps no asynchronous queue or durable history. // event, and Promptkit keeps no asynchronous queue or durable history.
type ExecutionObserver func(ExecutionEvent) type ExecutionObserver func(ExecutionEvent)
// WithExecutionObserver adds an observer to executions using the returned
// context. Inherited observers run before the newly added observer. A nil
// observer leaves the context unchanged.
func WithExecutionObserver(ctx context.Context, observer ExecutionObserver) context.Context {
if observer == nil {
return ctx
}
return observation.WithObserver(ctx, func(event domain.ExecutionEvent) {
observer(fromDomainExecutionEvent(event))
})
}
// ComposeObservers returns a synchronous ordered fan-out of non-nil observers. // ComposeObservers returns a synchronous ordered fan-out of non-nil observers.
// It copies the input slice; a panic propagates and prevents later callbacks. // It copies the input slice; a panic propagates and prevents later callbacks.
func ComposeObservers(observers ...ExecutionObserver) ExecutionObserver { func ComposeObservers(observers ...ExecutionObserver) ExecutionObserver {