Skip to content

Adds caller_context per ADR-0063 - #215

Merged
johnnyt merged 1 commit into
mainfrom
st-kahq-caller-context
Aug 22, 2026
Merged

Adds caller_context per ADR-0063#215
johnnyt merged 1 commit into
mainfrom
st-kahq-caller-context

Conversation

@johnnyt

@johnnyt johnnyt commented Aug 22, 2026

Copy link
Copy Markdown
Member

Why

The OTel bridge's handlers run in the session's own GenServer process, so
a sender's trace context is never ambient where a macrostep span opens,
and a durable timer firing hours later has no memory of the trace that
scheduled it. ADR-0063 decided the fix - an opaque caller_context :: term() the host sets at send time and the library carries without ever
reading - and sized the implementation onto this bead.

What

  • caller_context (default nil) on Statifier.Event,
    Effect.SendDelayed, and Effect.Cancel; settable only through
    Event.external/2's opts.
  • %MachineState{} gains the transient per-macrostep field with exactly
    three writers (handle_event/2 stamps the triggering event's slot;
    initialize/2 and cancel/1 stamp nil); the two durable-timer
    effect constructors copy it beside the counters, so the stamp is the
    core's and replay re-mints it byte-identically.
  • Session.Effects.delivered_event/2 / internal_event/1 copy the
    effect's slot onto the event a scheduled timer later delivers, so an
    in-process firing re-enters handle_event/2 carrying the scheduler's
    context.
  • Four telemetry events gain a caller_context metadata key (macrostep
    start/stop, effect send_delayed/cancel) - the ADR-0040 additive
    amendment; the contract table is updated.
  • Session.Recording format version bumps 2 -> 3; version-1/2 blobs
    decode with caller_context: nil defaulted onto stored events and
    durable-timer effects, with round-trip and hand-built-envelope tests.
  • Docs per ADR-0049 decision 6: opentelemetry.md's session-process
    caveat now names the field and its read points, durable-timers.md
    documents the row-data-never-key rule, persistence.md notes the bump
    and the host-term obligation. Changelog fragment included.

Notes

  • Full mix quality green (attested via mix gate.verify path) and
    mix quality --profile merge green (ADR judge: no findings). Every
    new test's sabotage mutation was run and confirmed red, then reverted.
  • ADR-0054's dedup and cancellation keys are untouched; _event does
    not surface the slot (spec 5.10.1).
  • The firing-side half for durable stores (restoring the context when a
    stored timer fires) belongs to statifier_oban's tracker (mirror bead
    sob-v28) and is not part of this change.

Closes st-kahq

Implements ADR-0063's opaque caller-context slot end to end:

- Statifier.Event, Effect.SendDelayed, and Effect.Cancel gain
  caller_context (term(), default nil); Event.external/2 reads the new
  :caller_context opt, internal/3 and platform/3 never do.
- MachineState gains the transient per-macrostep field with its three
  writers: handle_event/2 stamps the triggering event's slot,
  initialize/2 and cancel/1 stamp nil. The two durable-timer effect
  constructors copy it beside the counters they already read.
- Session.Effects' delivered_event/2 and internal_event/1 copy the
  effect's slot onto the event a scheduled timer later delivers.
- Four telemetry events gain a caller_context metadata key: macrostep
  start/stop and the send_delayed/cancel effect events (ADR-0040
  amendment; metadata, never a measurement).
- Recording format_version bumps 2 -> 3; version-1/2 blobs decode with
  caller_context: nil defaulted onto stored events and durable-timer
  effects.
- Docs: opentelemetry.md's session-process caveat now names the field
  and its read points; durable-timers.md carries the row-data rule;
  persistence.md notes the bump and the host-term obligation.

Refs: st-kahq
@johnnyt
johnnyt merged commit 2d9da98 into main Aug 22, 2026
1 check passed
@johnnyt
johnnyt deleted the st-kahq-caller-context branch August 22, 2026 14:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant