diff --git a/docs/internal/observation.md b/docs/internal/observation.md index baba922..a7ae601 100644 --- a/docs/internal/observation.md +++ b/docs/internal/observation.md @@ -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 preparation or execution. Delegated calls from an injected collaborator retain the caller's cancellation, deadline, and unrelated context values, but do not -reuse the enclosing invocation's accounting. Only the new request's observer -(or the claimed handle's retained observer) enables its observation lifecycle. +reuse the enclosing invocation's accounting. Ordinary runs compose the request +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 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 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 presence-aware usage exactly once. Snapshots copy members and totals under one lock; terminal coverage and token completeness are distinct. Observer fan-out 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 generation or HTTP collaborators. Their private attempt evidence is assembled diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 752829e..1214af2 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -72,6 +72,8 @@ a release, dependency upgrade, CLI implementation, or changes to published notes ## Stage 1 — Context Helper And Ordinary Run Selection +**Completed.** + Touch `observations.go`, the root `Engine.Run` in `engine.go`, and context support in `internal/observation/recorder.go` or a focused adjacent file. diff --git a/engine.go b/engine.go index c758f11..053b57d 100644 --- a/engine.go +++ b/engine.go @@ -605,13 +605,18 @@ func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error) { scope := usecase.NewOperationScope(ctx, req.OperationTimeout) defer scope.Close() 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) err = mapPublicError(scope.Finalize(err)) scope.Close() 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 { recorder.SetParentRunID(req.ContinueFrom.internal.RunID()) } diff --git a/internal/observation/recorder.go b/internal/observation/recorder.go index fb24b70..a076a94 100644 --- a/internal/observation/recorder.go +++ b/internal/observation/recorder.go @@ -195,6 +195,22 @@ func (r *Recorder) deliver(event domain.ExecutionEvent) { 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 // invocation's recorder or prepared-claim sink. Other context values and all // cancellation/deadline behavior remain with the caller's context. diff --git a/observation_boundary_contract_test.go b/observation_boundary_contract_test.go index 9be67ca..35b7fca 100644 --- a/observation_boundary_contract_test.go +++ b/observation_boundary_contract_test.go @@ -4,6 +4,7 @@ import ( "context" "errors" "fmt" + "reflect" "testing" "time" @@ -11,6 +12,66 @@ import ( "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) func (f observationClientFunc) Generate(ctx context.Context, req promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) { diff --git a/observations.go b/observations.go index f999fe8..c132318 100644 --- a/observations.go +++ b/observations.go @@ -17,6 +17,18 @@ import ( // event, and Promptkit keeps no asynchronous queue or durable history. 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. // It copies the input slice; a panic propagates and prevents later callbacks. func ComposeObservers(observers ...ExecutionObserver) ExecutionObserver {