Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Order the event stream: nanosecond timestamps and a per-writer sequence

Claudee64b212de7db
diff --git a/beacon-sandbox/check/check_test.go b/beacon-sandbox/check/check_test.go
index b0fcae50..26baa3e9 100644
--- a/beacon-sandbox/check/check_test.go
+++ b/beacon-sandbox/check/check_test.go
@@ -19,9 +19,9 @@ const canary = "BEACON_E2E_TESTCANARY"
// goodLog is a minimal but schema-valid stream shaped like a real Claude Code session.
func goodLog() []string {
return []string{
- `{"timestamp":"2026-08-02T18:00:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"prompt.submitted","category":"prompt"},"severity":"info","endpoint":{"os":"linux","hostname":"sandbox"},"harness":{"name":"claude_code"},"session":{"id":"s1"},"prompt":{"text":"run echo ` + canary + `"},"message":"claude_code.user_prompt"}`,
- `{"timestamp":"2026-08-02T18:00:01Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"command.executed","category":"command"},"severity":"info","endpoint":{"os":"linux","hostname":"sandbox"},"harness":{"name":"claude_code"},"session":{"id":"s1"},"tool":{"name":"Bash"},"command":{"command":"echo ` + canary + `"},"message":"claude_code.tool_result"}`,
- `{"timestamp":"2026-08-02T18:00:02Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},"severity":"info","endpoint":{"os":"linux","hostname":"sandbox"},"harness":{"name":"claude_code"},"session":{"id":"s1"},"model":"claude-opus-5","gen_ai":{"usage":{"input_tokens":100}},"message":"claude_code.token.usage"}`,
+ `{"timestamp":"2026-08-02T18:00:00.000000000Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"prompt.submitted","category":"prompt"},"severity":"info","endpoint":{"os":"linux","hostname":"sandbox"},"harness":{"name":"claude_code"},"session":{"id":"s1"},"prompt":{"text":"run echo ` + canary + `"},"message":"claude_code.user_prompt"}`,
+ `{"timestamp":"2026-08-02T18:00:01.000000000Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"command.executed","category":"command"},"severity":"info","endpoint":{"os":"linux","hostname":"sandbox"},"harness":{"name":"claude_code"},"session":{"id":"s1"},"tool":{"name":"Bash"},"command":{"command":"echo ` + canary + `"},"message":"claude_code.tool_result"}`,
+ `{"timestamp":"2026-08-02T18:00:02.000000000Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},"severity":"info","endpoint":{"os":"linux","hostname":"sandbox"},"harness":{"name":"claude_code"},"session":{"id":"s1"},"model":"claude-opus-5","gen_ai":{"usage":{"input_tokens":100}},"message":"claude_code.token.usage"}`,
}
}
@@ -260,7 +260,7 @@ func TestMissingEventWithoutSentinelFails(t *testing.T) {
// writer would never have collapsed. Cursor Bugbot caught it; the test was wrong, not the fix.
func TestSameHarnessRepeatsSurviveWithoutMatchingCallIDs(t *testing.T) {
base := goodLog()
- dup := strings.Replace(base[1], "18:00:01Z", "18:00:02Z", 1) // 1s apart, no call IDs
+ dup := strings.Replace(base[1], "18:00:01.000000000Z", "18:00:02.000000000Z", 1) // 1s apart, no call IDs
sc := demoScenario()
sc.Expect = []scenario.Expect{{
@@ -280,13 +280,13 @@ func TestSameHarnessRepeatsSurviveWithoutMatchingCallIDs(t *testing.T) {
func TestMatchingCallIDsInsideTheWindowCollapse(t *testing.T) {
base := goodLog()
withID := func(line, ts, id string) string {
- line = strings.Replace(line, "18:00:01Z", ts, 1)
+ line = strings.Replace(line, "18:00:01.000000000Z", ts, 1)
return strings.Replace(line, `"tool":{"name":"Bash"}`,
`"tool":{"name":"Bash"},"gen_ai":{"tool":{"call":{"id":"`+id+`"}}}`, 1)
}
- first := withID(base[1], "18:00:01Z", "call-1")
- same := withID(base[1], "18:00:02Z", "call-1") // 1s apart, identical call id
- later := withID(base[1], "18:00:11Z", "call-1") // 10s apart, outside the 2s window
+ first := withID(base[1], "18:00:01.000000000Z", "call-1")
+ same := withID(base[1], "18:00:02.000000000Z", "call-1") // 1s apart, identical call id
+ later := withID(base[1], "18:00:11.000000000Z", "call-1") // 10s apart, outside the 2s window
sc := demoScenario()
sc.Expect = []scenario.Expect{{
@@ -311,7 +311,7 @@ func TestMatchingCallIDsInsideTheWindowCollapse(t *testing.T) {
func TestNonCandidateActionsAreNeverCollapsed(t *testing.T) {
base := goodLog()
// token.usage is not in the writer's dedupe set, so two 1s apart both count.
- dup := strings.Replace(base[2], "18:00:02Z", "18:00:03Z", 1)
+ dup := strings.Replace(base[2], "18:00:02.000000000Z", "18:00:03.000000000Z", 1)
sc := demoScenario()
sc.Expect = []scenario.Expect{{
@@ -730,15 +730,15 @@ func TestTimestampOrderOnlyWarnsOnLargeRegressions(t *testing.T) {
sc.Expect = []scenario.Expect{{Action: "session.activity", Why: "baseline"}}
// Forward progress, plus a 1s hiccup well inside the 5s tolerance.
- fine := run(t, []string{at("2026-08-02T18:00:00Z"), at("2026-08-02T18:00:10Z"),
- at("2026-08-02T18:00:09Z")}, sc, Sentinel{}, nil)
+ fine := run(t, []string{at("2026-08-02T18:00:00.000000000Z"), at("2026-08-02T18:00:10.000000000Z"),
+ at("2026-08-02T18:00:09.000000000Z")}, sc, Sentinel{}, nil)
if hasCheck(fine, "invariant.timestamp_order") {
t.Errorf("a 1s hiccup is inside the tolerance and must not warn:\n%s", fine.Report())
}
// A 30s backwards jump is outside it.
- regressed := run(t, []string{at("2026-08-02T18:00:00Z"), at("2026-08-02T18:01:00Z"),
- at("2026-08-02T18:00:30Z")}, sc, Sentinel{}, nil)
+ regressed := run(t, []string{at("2026-08-02T18:00:00.000000000Z"), at("2026-08-02T18:01:00.000000000Z"),
+ at("2026-08-02T18:00:30.000000000Z")}, sc, Sentinel{}, nil)
if !hasCheck(regressed, "invariant.timestamp_order") {
t.Errorf("a 30s backwards jump must warn:\n%s", regressed.Report())
}
diff --git a/beacon-sandbox/check/expect.go b/beacon-sandbox/check/expect.go
index adfc9b53..5934a2b4 100644
--- a/beacon-sandbox/check/expect.go
+++ b/beacon-sandbox/check/expect.go
@@ -7,6 +7,7 @@ import (
"time"
"github.com/asymptote-labs/agent-beacon/beacon-sandbox/scenario"
+ obs "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
// DuplicateWindow mirrors IsDuplicateEndpointEvent's suppression window in the writer.
@@ -244,7 +245,7 @@ func collapseDuplicates(events []Event) []Event {
out = append(out, e)
continue
}
- ts, err := time.Parse(time.RFC3339, e.Typed.Timestamp)
+ ts, err := obs.ParseTimestamp(e.Typed.Timestamp)
if err != nil {
out = append(out, e)
continue
@@ -261,7 +262,7 @@ func collapseDuplicates(events []Event) []Event {
continue
}
}
- pts, err := time.Parse(time.RFC3339, prev.Typed.Timestamp)
+ pts, err := obs.ParseTimestamp(prev.Typed.Timestamp)
if err != nil {
continue
}
diff --git a/beacon-sandbox/check/invariants.go b/beacon-sandbox/check/invariants.go
index ffd06e3b..68bda6b5 100644
--- a/beacon-sandbox/check/invariants.go
+++ b/beacon-sandbox/check/invariants.go
@@ -69,6 +69,7 @@ func Invariants(v *Verdict, log Log, secrets Secrets) {
checkSchema(v, log)
checkSizes(v, log)
checkTimestamps(v, log)
+ checkOrdering(v, log)
checkActions(v, log)
checkSecrets(v, log, secrets)
}
@@ -146,7 +147,7 @@ func checkTimestamps(v *Verdict, log Log) {
if e.ParseErr != nil {
continue
}
- ts, err := time.Parse(time.RFC3339, e.Typed.Timestamp)
+ ts, err := obs.ParseTimestamp(e.Typed.Timestamp)
if err != nil {
unparseable = append(unparseable, fmt.Sprintf("%s:%d (%q)", log.Path, e.Line, e.Typed.Timestamp))
continue
@@ -186,6 +187,94 @@ func checkTimestamps(v *Verdict, log Log) {
}
}
+// checkOrdering requires the log to be orderable: sub-second timestamps, and a sequence
+// on the events that share one anyway.
+//
+// The pathology it exists for was measured, not imagined: in a 5,595-event runtime log,
+// zero events carried a sub-second timestamp and 97% shared a timestamp with another event
+// in the same session, so nothing downstream could tell which of two events came first and
+// ordered detection fell back to the order the lines happened to land in the file.
+//
+// A log with no sub-second timestamp at all is that regression returning, and fails. A log
+// where only some events carry one is a log spanning an agent upgrade, which is expected
+// and only warns.
+func checkOrdering(v *Verdict, log Log) {
+ var (
+ stamped int
+ parseable int
+ collided []string
+ )
+ seen := map[string]string{}
+ for _, e := range log.Events {
+ if e.ParseErr != nil {
+ continue
+ }
+ ts := e.Typed.Timestamp
+ if _, err := obs.ParseTimestamp(ts); err != nil {
+ continue
+ }
+ parseable++
+ if strings.Contains(ts, ".") {
+ stamped++
+ }
+ session := ""
+ if e.Typed.Session != nil {
+ session = e.Typed.Session.ID
+ }
+ // A shared timestamp is only a problem when nothing else separates the two events.
+ if e.Typed.Sequence != 0 {
+ continue
+ }
+ key := session + "\x00" + ts
+ if previous, ok := seen[key]; ok {
+ collided = append(collided, fmt.Sprintf("%s:%d (%s, shared with %s, neither sequenced)",
+ log.Path, e.Line, ts, previous))
+ continue
+ }
+ seen[key] = fmt.Sprintf("%s:%d", log.Path, e.Line)
+ }
+
+ if parseable > 0 && stamped == 0 {
+ v.Add(Finding{
+ Check: "invariant.timestamp_precision", Severity: SevFail,
+ Summary: fmt.Sprintf("0 of %d event(s) carry a sub-second timestamp", parseable),
+ Why: "without sub-second stamping most events in a session share a timestamp, and nothing can order them",
+ Evidence: cap5(firstTimestamps(log)),
+ })
+ } else if stamped < parseable {
+ v.Add(Finding{
+ Check: "invariant.timestamp_precision", Severity: SevWarn,
+ Summary: fmt.Sprintf("%d of %d event(s) carry a second-resolution timestamp",
+ parseable-stamped, parseable),
+ Why: "expected in a log written across an agent upgrade; otherwise a writer is not stamping canonically",
+ })
+ }
+ if len(collided) > 0 {
+ v.Add(Finding{
+ Check: "invariant.event_orderable", Severity: SevWarn,
+ Summary: fmt.Sprintf("%d event(s) share a session timestamp with no sequence to separate them", len(collided)),
+ Why: "two events that tie on both keys can only be ordered by where they landed in the file",
+ Evidence: cap5(collided),
+ })
+ }
+}
+
+// firstTimestamps returns the timestamps of the first few parseable events, as evidence for
+// a precision finding.
+func firstTimestamps(log Log) []string {
+ var out []string
+ for _, e := range log.Events {
+ if e.ParseErr != nil || e.Typed.Timestamp == "" {
+ continue
+ }
+ out = append(out, fmt.Sprintf("%s:%d (%q)", log.Path, e.Line, e.Typed.Timestamp))
+ if len(out) == 5 {
+ break
+ }
+ }
+ return out
+}
+
func checkActions(v *Verdict, log Log) {
unknown := map[string][]string{}
for _, e := range log.Events {
diff --git a/beacon-sandbox/check/ordering_test.go b/beacon-sandbox/check/ordering_test.go
new file mode 100644
index 00000000..08c83872
--- /dev/null
+++ b/beacon-sandbox/check/ordering_test.go
@@ -0,0 +1,117 @@
+package check
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/beacon-sandbox/scenario"
+)
+
+// orderingScenario expects only the event these tests emit, so the outcome reflects the
+// ordering invariants rather than unmet capture expectations.
+func orderingScenario() scenario.Scenario {
+ sc := demoScenario()
+ sc.Sentinel = ""
+ sc.Expect = []scenario.Expect{{Action: "session.activity", Why: "baseline"}}
+ return sc
+}
+
+// activity builds a session.activity event at ts, optionally carrying a sequence.
+func activity(ts string, sequence string) string {
+ line := `{"timestamp":"` + ts + `",`
+ if sequence != "" {
+ line += `"sequence":` + sequence + `,`
+ }
+ return line + `"vendor":"beacon","product":"endpoint-agent","schema_version":"1.0",` +
+ `"event":{"kind":"agent_runtime","action":"session.activity","category":"session"},` +
+ `"severity":"info","endpoint":{"os":"linux","hostname":"sandbox"},` +
+ `"harness":{"name":"claude_code"},"session":{"id":"s1"},"message":"m"}`
+}
+
+func TestSecondResolutionLogFailsPrecision(t *testing.T) {
+ // The measured regression: not one event in the log carries a sub-second timestamp, so
+ // nothing downstream can order two events in the same second.
+ v := run(t, []string{
+ activity("2026-08-02T18:00:00Z", ""),
+ activity("2026-08-02T18:00:01Z", ""),
+ }, orderingScenario(), Sentinel{}, nil)
+
+ if !hasCheck(v, "invariant.timestamp_precision") {
+ t.Fatalf("a log with no sub-second timestamp must be reported:\n%s", v.Report())
+ }
+ if v.Outcome != Fail {
+ t.Fatalf("outcome = %v, want Fail:\n%s", v.Outcome, v.Report())
+ }
+}
+
+func TestMixedPrecisionLogWarnsWithoutFailing(t *testing.T) {
+ // A log written across an agent upgrade holds both forms. That is expected, so it is
+ // worth saying and not worth failing.
+ v := run(t, []string{
+ activity("2026-08-02T18:00:00Z", ""),
+ activity("2026-08-02T18:00:01.500000000Z", ""),
+ }, orderingScenario(), Sentinel{}, nil)
+
+ if !hasCheck(v, "invariant.timestamp_precision") {
+ t.Fatalf("a partly second-resolution log must be reported:\n%s", v.Report())
+ }
+ if v.Outcome == Fail {
+ t.Fatalf("a mixed-precision log is a warning, not a failure:\n%s", v.Report())
+ }
+ if !strings.Contains(v.Report(), "second-resolution timestamp") {
+ t.Fatalf("report should name what is second-resolution:\n%s", v.Report())
+ }
+}
+
+func TestCanonicalLogReportsNoOrderingFinding(t *testing.T) {
+ v := run(t, []string{
+ activity("2026-08-02T18:00:00.000000000Z", "1"),
+ activity("2026-08-02T18:00:00.250000000Z", "2"),
+ }, orderingScenario(), Sentinel{}, nil)
+
+ if hasCheck(v, "invariant.timestamp_precision") || hasCheck(v, "invariant.event_orderable") {
+ t.Fatalf("a canonically stamped log must report no ordering finding:\n%s", v.Report())
+ }
+ // Also the baseline for the tests above: this scenario passes on a canonical log, so a
+ // Fail there is attributable to the ordering invariant rather than to the scenario.
+ if v.Outcome != Pass {
+ t.Fatalf("outcome = %v, want Pass:\n%s", v.Outcome, v.Report())
+ }
+}
+
+func TestSharedTimestampWithoutSequenceIsReported(t *testing.T) {
+ // Two events tied on the timestamp and neither numbered: only the order they landed in
+ // the file separates them, which is exactly what this workstream stops relying on.
+ tie := "2026-08-02T18:00:00.000000000Z"
+ v := run(t, []string{activity(tie, ""), activity(tie, "")}, orderingScenario(), Sentinel{}, nil)
+
+ if !hasCheck(v, "invariant.event_orderable") {
+ t.Fatalf("an unorderable pair must be reported:\n%s", v.Report())
+ }
+ if v.Outcome == Fail {
+ t.Fatalf("an unorderable pair is a warning, not a failure:\n%s", v.Report())
+ }
+}
+
+func TestSharedTimestampWithSequenceIsOrderable(t *testing.T) {
+ // The tie a more precise clock cannot break -- one metric export's datapoints -- is
+ // resolved by the sequence, so it is not a finding.
+ tie := "2026-08-02T18:00:00.000000000Z"
+ v := run(t, []string{activity(tie, "11"), activity(tie, "12")}, orderingScenario(), Sentinel{}, nil)
+
+ if hasCheck(v, "invariant.event_orderable") {
+ t.Fatalf("a sequenced tie is orderable and must not be reported:\n%s", v.Report())
+ }
+}
+
+func TestSharedTimestampAcrossSessionsIsNotATie(t *testing.T) {
+ // Ordering is only ever asked within a session, so two sessions stamping the same
+ // instant is not a collision.
+ tie := "2026-08-02T18:00:00.000000000Z"
+ other := strings.Replace(activity(tie, ""), `"id":"s1"`, `"id":"s2"`, 1)
+ v := run(t, []string{activity(tie, ""), other}, orderingScenario(), Sentinel{}, nil)
+
+ if hasCheck(v, "invariant.event_orderable") {
+ t.Fatalf("timestamps shared across sessions are not a tie:\n%s", v.Report())
+ }
+}
diff --git a/cli/beacon-hooks/internal/logging/endpoint_event_test.go b/cli/beacon-hooks/internal/logging/endpoint_event_test.go
index ab9c747b..fc0a3477 100644
--- a/cli/beacon-hooks/internal/logging/endpoint_event_test.go
+++ b/cli/beacon-hooks/internal/logging/endpoint_event_test.go
@@ -6,6 +6,8 @@ import (
"path/filepath"
"strings"
"testing"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
func TestEndpointRedaction(t *testing.T) {
@@ -229,3 +231,92 @@ func TestEndpointEventSurfacesWriteFailure(t *testing.T) {
t.Fatal("EndpointEvent returned nil, want write failure")
}
}
+
+func TestEndpointEventStampsSubSecondTimestamp(t *testing.T) {
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ logger := NewLoggerForPlatform("pre-tool", "cursor")
+ if err := logger.EndpointEvent("tool.started", "tool", "info", "observed", nil); err != nil {
+ t.Fatalf("EndpointEvent returned error: %v", err)
+ }
+
+ event := readEndpointEvents(t, logPath)[0]
+ timestamp, _ := event["timestamp"].(string)
+ if _, err := asymptoteobserve.ParseTimestamp(timestamp); err != nil {
+ t.Fatalf("timestamp %q does not parse: %v", timestamp, err)
+ }
+ if !strings.Contains(timestamp, ".") {
+ t.Fatalf("timestamp = %q, want sub-second precision", timestamp)
+ }
+}
+
+func TestEndpointEventNumbersEventsWithinOneHookInvocation(t *testing.T) {
+ // A post-tool hook records the tool result, the file edit and the command in one
+ // process. On a coarse clock those can land on the same timestamp, and the sequence
+ // is what still says which came first.
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ logger := NewLoggerForPlatform("post-tool", "cursor")
+ for _, action := range []string{"tool.completed", "file.edited", "command.executed"} {
+ if err := logger.EndpointEvent(action, "tool", "info", action, nil); err != nil {
+ t.Fatalf("EndpointEvent(%s) returned error: %v", action, err)
+ }
+ }
+
+ var previous float64
+ for i, event := range readEndpointEvents(t, logPath) {
+ sequence, ok := event["sequence"].(float64)
+ if !ok {
+ t.Fatalf("event %d has no sequence: %v", i, event)
+ }
+ if sequence < 1 {
+ t.Fatalf("event %d sequence = %v, want at least 1 (0 means unsequenced)", i, sequence)
+ }
+ if i > 0 && sequence <= previous {
+ t.Fatalf("event %d sequence = %v, want greater than %v", i, sequence, previous)
+ }
+ previous = sequence
+ }
+}
+
+func TestMinimalEndpointEventKeepsOrderingFields(t *testing.T) {
+ // The oversized-event fallback strips the event down to metadata. Dropping the
+ // ordering keys there would leave exactly the events most worth ordering unorderable.
+ minimal := minimalEndpointEvent(map[string]interface{}{
+ "timestamp": "2026-08-21T10:00:00.000000000Z",
+ "sequence": uint64(42),
+ "message": "big",
+ })
+ if minimal["timestamp"] != "2026-08-21T10:00:00.000000000Z" {
+ t.Fatalf("minimal timestamp = %v", minimal["timestamp"])
+ }
+ if minimal["sequence"] != uint64(42) {
+ t.Fatalf("minimal sequence = %v, want 42", minimal["sequence"])
+ }
+}
+
+// readEndpointEvents decodes every event written to the runtime log.
+func readEndpointEvents(t *testing.T, path string) []map[string]interface{} {
+ t.Helper()
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read %s: %v", path, err)
+ }
+ var events []map[string]interface{}
+ for _, line := range strings.Split(strings.TrimSpace(string(data)), "\n") {
+ if line == "" {
+ continue
+ }
+ var event map[string]interface{}
+ if err := json.Unmarshal([]byte(line), &event); err != nil {
+ t.Fatalf("decode %q: %v", line, err)
+ }
+ events = append(events, event)
+ }
+ if len(events) == 0 {
+ t.Fatalf("no events written to %s", path)
+ }
+ return events
+}
diff --git a/cli/beacon-hooks/internal/logging/logging.go b/cli/beacon-hooks/internal/logging/logging.go
index ff018796..0ab43133 100644
--- a/cli/beacon-hooks/internal/logging/logging.go
+++ b/cli/beacon-hooks/internal/logging/logging.go
@@ -15,6 +15,10 @@ import (
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/filelock"
)
+// endpointSequence numbers the endpoint events emitted by this hook process, in the order
+// they are written.
+var endpointSequence asymptoteobserve.Sequencer
+
const (
defaultEndpointRotateBytes = 10 * 1024 * 1024
defaultEndpointRotateArchives = 5
@@ -126,7 +130,14 @@ func (l *Logger) baseEndpointEvent(action, category, severity, message string) m
user["uid"] = uid
}
event := map[string]interface{}{
- "timestamp": time.Now().UTC().Format(time.RFC3339),
+ "timestamp": asymptoteobserve.FormatTimestamp(time.Now()),
+ // Emission order within this hook invocation. One invocation can emit several
+ // events (a post-tool hook records the tool result, the file edit and the command
+ // in turn), and on a coarse clock those can land on the same nanosecond -- the
+ // counter is what still separates them. It restarts at 1 in every hook process,
+ // which is why it is a tiebreaker under the timestamp rather than an ordering key
+ // of its own; see asymptoteobserve.Event.Sequence.
+ "sequence": endpointSequence.Next(),
"vendor": "beacon",
"product": "endpoint-agent",
"schema_version": "1.0",
@@ -281,7 +292,7 @@ func compactEndpointContent(event map[string]interface{}) {
func minimalEndpointEvent(event map[string]interface{}) map[string]interface{} {
out := map[string]interface{}{"field_truncated": true}
for _, key := range []string{
- "timestamp", "vendor", "product", "schema_version", "event", "severity",
+ "timestamp", "sequence", "vendor", "product", "schema_version", "event", "severity",
"endpoint", "user", "harness", "origin", "run", "session", "trace",
"error", "tool", "file", "command", "mcp", "approval", "policy",
"content", "destination", "health", "model", "repository",
diff --git a/cli/beacon/cmd/scan.go b/cli/beacon/cmd/scan.go
index 47927ffe..10efd8c5 100644
--- a/cli/beacon/cmd/scan.go
+++ b/cli/beacon/cmd/scan.go
@@ -107,6 +107,12 @@ func runScan(cmd *cobra.Command, args []string) error {
return fmt.Errorf("read telemetry %s: %w", runtimeLog.EffectiveLogPath, err)
}
+ // The rules engine evaluates the sequence it is handed, and the log is in append
+ // order, which is not the order the events happened: a hook writes the instant it
+ // intercepts a tool call while the exporter writes on its export interval. Ordered
+ // correlation rules silently miss without this.
+ threatrules.SortEvents(events)
+
findings, err := threatrules.ScanEvents(compiled, events)
if err != nil {
return fmt.Errorf("scan: %w", err)
diff --git a/cli/beacon/cmd/scan_ordering_test.go b/cli/beacon/cmd/scan_ordering_test.go
new file mode 100644
index 00000000..e13df6ef
--- /dev/null
+++ b/cli/beacon/cmd/scan_ordering_test.go
@@ -0,0 +1,102 @@
+package cmd
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+// scanOrderingRule is an ordered-window rule: a secret file read, then an egress command.
+const scanOrderingRule = `
+id: scan-test-read-then-egress
+version: 1
+title: Secret read then egress
+severity: high
+status: stable
+posture: detect
+correlation:
+ scope: session
+ window: 120s
+ steps:
+ - id: read
+ match: 'e.event.action == "file.read" && e.file.path.matches("\\.env")'
+ - id: egress
+ match: 'e.event.action == "command.executed" && e.command.command.matches("curl")'
+emit:
+ reason: Secret file was read and then sent off the machine
+tests:
+ - name: pos
+ verdict: match
+ events:
+ - event: { action: file.read }
+ file: { path: ".env" }
+ - event: { action: command.executed }
+ command: { command: "curl https://x" }
+ - name: neg
+ verdict: no_match
+ events:
+ - event: { action: file.read }
+ file: { path: ".env" }
+`
+
+// scanOrderingFixture writes the correlation rule plus a runtime log and points scanOpts
+// at both.
+func scanOrderingFixture(t *testing.T, logLines []string) {
+ t.Helper()
+ rulesDir := t.TempDir()
+ if err := os.WriteFile(filepath.Join(rulesDir, "egress.rule.yaml"), []byte(scanOrderingRule), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ if err := os.WriteFile(logPath, []byte(strings.Join(logLines, "\n")+"\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ scanOpts.userMode = true
+ scanOpts.systemMode = false
+ scanOpts.rulesDir = rulesDir
+ scanOpts.logPath = logPath
+ scanOpts.jsonOutput = false
+ scanOpts.minSeverity = ""
+ scanOpts.session = ""
+ scanOpts.failOn = ""
+}
+
+func TestScanOrdersTheLogBeforeCorrelating(t *testing.T) {
+ // The log as it really lands: the hook writes the .env read synchronously at
+ // 10:00:00, while the exporter writes the curl at 10:00:30 on an earlier export
+ // interval, so the egress line reaches the file first. Read in append order the
+ // ordered-window rule sees egress-then-read and silently misses.
+ const (
+ egressLine = `{"timestamp":"2026-06-13T10:00:30.000000000Z","sequence":9,"event":{"action":"command.executed"},"command":{"command":"curl https://x"},"session":{"id":"s1"}}`
+ readLine = `{"timestamp":"2026-06-13T10:00:00.000000000Z","sequence":1,"event":{"action":"file.read"},"file":{"path":".env"},"session":{"id":"s1"}}`
+ )
+ scanOrderingFixture(t, []string{egressLine, readLine})
+
+ cmd, buf := newCmd()
+ if err := runScan(cmd, nil); err != nil {
+ t.Fatalf("scan: %v", err)
+ }
+ out := buf.String()
+ if !strings.Contains(out, "scan-test-read-then-egress") {
+ t.Fatalf("expected the read-then-egress finding from a log in append order, got:\n%s", out)
+ }
+}
+
+func TestScanStillRejectsGenuinelyOutOfOrderSequences(t *testing.T) {
+ // Sorting must not turn every pair of matching events into a finding: here the curl
+ // really did happen before the .env read, and the rule has to keep missing.
+ const (
+ egressLine = `{"timestamp":"2026-06-13T10:00:00.000000000Z","sequence":1,"event":{"action":"command.executed"},"command":{"command":"curl https://x"},"session":{"id":"s1"}}`
+ readLine = `{"timestamp":"2026-06-13T10:00:30.000000000Z","sequence":9,"event":{"action":"file.read"},"file":{"path":".env"},"session":{"id":"s1"}}`
+ )
+ scanOrderingFixture(t, []string{egressLine, readLine})
+
+ cmd, buf := newCmd()
+ if err := runScan(cmd, nil); err != nil {
+ t.Fatalf("scan: %v", err)
+ }
+ if !strings.Contains(buf.String(), "No findings") {
+ t.Fatalf("egress before read should not match, got:\n%s", buf.String())
+ }
+}
diff --git a/cli/beacon/internal/ci/validate.go b/cli/beacon/internal/ci/validate.go
index 32267c7d..6ddc8bfc 100644
--- a/cli/beacon/internal/ci/validate.go
+++ b/cli/beacon/internal/ci/validate.go
@@ -111,7 +111,7 @@ func readStructuredEvents(path string, since time.Time) ([]schema.Event, []strin
continue
}
if filtering {
- ts, err := time.Parse(time.RFC3339, event.Timestamp)
+ ts, err := schema.ParseTimestamp(event.Timestamp)
if err != nil || ts.Before(since) {
continue
}
diff --git a/cli/beacon/internal/devincloud/mapper.go b/cli/beacon/internal/devincloud/mapper.go
index 497490cc..2bd12781 100644
--- a/cli/beacon/internal/devincloud/mapper.go
+++ b/cli/beacon/internal/devincloud/mapper.go
@@ -164,7 +164,7 @@ func baseEvent(s Session, action, category string, severity schema.Severity, tsU
},
})
if tsUnix > 0 {
- ev.Timestamp = time.Unix(tsUnix, 0).UTC().Format(time.RFC3339)
+ ev.Timestamp = schema.FormatTimestamp(time.Unix(tsUnix, 0))
}
ev.Session = &schema.SessionInfo{ID: s.SessionID}
if repo != "" {
diff --git a/cli/beacon/internal/devincloud/mapper_test.go b/cli/beacon/internal/devincloud/mapper_test.go
index 8ca77ebf..fc5e8b77 100644
--- a/cli/beacon/internal/devincloud/mapper_test.go
+++ b/cli/beacon/internal/devincloud/mapper_test.go
@@ -65,8 +65,11 @@ func TestMapSessionProducesLifecycleAndMessages(t *testing.T) {
t.Fatalf("agent message = %q, want done", mapped[2].Event.Message)
}
- // Timestamps come from the source unix times.
- if mapped[0].Event.Timestamp != "1970-01-01T00:16:40Z" {
+ // Timestamps come from the source unix times, rendered in the canonical event
+ // format. Devin reports whole seconds, so the sub-second digits are zeros -- the
+ // width is fixed so that every event in the stream sorts byte-wise as well as
+ // chronologically.
+ if mapped[0].Event.Timestamp != "1970-01-01T00:16:40.000000000Z" {
t.Fatalf("started ts = %q, want session created_at", mapped[0].Event.Timestamp)
}
}
diff --git a/cli/beacon/internal/endpoint/dashboard/detections.go b/cli/beacon/internal/endpoint/dashboard/detections.go
index 6154bfa7..de408680 100644
--- a/cli/beacon/internal/endpoint/dashboard/detections.go
+++ b/cli/beacon/internal/endpoint/dashboard/detections.go
@@ -118,6 +118,12 @@ func RunScan(userMode bool, logPath, rulesDir, session, minSeverity string) (Fin
return FindingsResponse{}, fmt.Errorf("read telemetry %s: %w", logPath, err)
}
+ // The rules engine evaluates the sequence it is handed, and the log is in append
+ // order, which is not the order the events happened: a hook writes the instant it
+ // intercepts a tool call while the exporter writes on its export interval. Ordered
+ // correlation rules silently miss without this.
+ threatrules.SortEvents(events)
+
findings, err := threatrules.ScanEvents(compiled, events)
if err != nil {
return FindingsResponse{}, fmt.Errorf("scan: %w", err)
diff --git a/cli/beacon/internal/endpoint/dashboard/events.go b/cli/beacon/internal/endpoint/dashboard/events.go
index 89b666ac..f56b83b0 100644
--- a/cli/beacon/internal/endpoint/dashboard/events.go
+++ b/cli/beacon/internal/endpoint/dashboard/events.go
@@ -13,6 +13,7 @@ import (
"time"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
const (
@@ -157,17 +158,26 @@ func streamSource(source eventSource, fn func(schema.Event) error) error {
return scanner.Err()
}
-// SortRecordsAppendOrder orders records oldest-first in log append order: by
-// timestamp, then older archives before the live log, then by numeric line.
-// Token aggregation needs this because runtime timestamps are second-resolution
-// (a batch of cumulative datapoints shares a timestamp) and the cumulative
-// dedup relies on append order; the newest-first ReadEvents sort breaks ties on
-// lexicographic line IDs, which mis-orders line-9 vs line-10 within a second.
+// SortRecordsAppendOrder orders records oldest-first: by timestamp, then by the
+// emitting writer's sequence, then older archives before the live log, then by
+// numeric line.
+//
+// Token aggregation needs this because a single metric export flushes a batch of
+// cumulative datapoints that all carry that export's collection instant, so they
+// tie on the timestamp however precise it is, and the cumulative dedup needs
+// their emission order back. Sequence recovers it directly; the archive-and-line
+// tiebreak below is the fallback for events written before sequence stamping,
+// and is still needed because the newest-first ReadEvents sort breaks ties on
+// lexicographic line IDs, which mis-orders line-9 against line-10.
func SortRecordsAppendOrder(records []EventRecord) {
sort.SliceStable(records, func(i, j int) bool {
if !records[i].Parsed.Equal(records[j].Parsed) {
return records[i].Parsed.Before(records[j].Parsed)
}
+ si, sj := records[i].Event.Sequence, records[j].Event.Sequence
+ if si != 0 && sj != 0 && si != sj {
+ return si < sj
+ }
ai, li, _ := parseRecordID(records[i].ID)
aj, lj, _ := parseRecordID(records[j].ID)
if ai != aj {
@@ -204,7 +214,7 @@ func readEventsFromSource(source eventSource, query EventQuery, result *EventRes
continue
}
normalizeDashboardEvent(&event)
- parsed, _ := time.Parse(time.RFC3339, event.Timestamp)
+ parsed, _ := asymptoteobserve.ParseTimestamp(event.Timestamp)
record := EventRecord{
ID: source.lineID(lineNo),
Line: lineNo,
@@ -271,7 +281,7 @@ func FindEvent(path, id string) (EventRecord, bool, error) {
return EventRecord{}, false, nil
}
normalizeDashboardEvent(&event)
- parsed, _ := time.Parse(time.RFC3339, event.Timestamp)
+ parsed, _ := asymptoteobserve.ParseTimestamp(event.Timestamp)
return EventRecord{
ID: source.lineID(lineNo),
Line: lineNo,
diff --git a/cli/beacon/internal/endpoint/dashboard/ordering_test.go b/cli/beacon/internal/endpoint/dashboard/ordering_test.go
new file mode 100644
index 00000000..72700fcf
--- /dev/null
+++ b/cli/beacon/internal/endpoint/dashboard/ordering_test.go
@@ -0,0 +1,111 @@
+package dashboard
+
+import (
+ "path/filepath"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+)
+
+func TestReadEventsAppendOrderBreaksTimestampTiesOnSequence(t *testing.T) {
+ // A batch of cumulative datapoints from one export shares a timestamp however precise
+ // the timestamp is, and token aggregation needs their emission order back. The file
+ // deliberately holds them in the wrong order to prove the sequence is what recovers it
+ // rather than the line number.
+ tie := "2026-05-13T01:00:00.000000000Z"
+ first := testSchemaEvent(tie, "claude_code", "metric.observed", "metric", "")
+ first.Sequence = 11
+ first.Message = "first"
+ second := testSchemaEvent(tie, "claude_code", "metric.observed", "metric", "")
+ second.Sequence = 12
+ second.Message = "second"
+
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ writeTestLog(t, path, marshalEvents(t, second, first)...)
+
+ events, err := ReadEventsAppendOrder(path, EventQuery{})
+ if err != nil {
+ t.Fatalf("ReadEventsAppendOrder returned error: %v", err)
+ }
+ if len(events) != 2 {
+ t.Fatalf("read %d events, want 2", len(events))
+ }
+ if events[0].Message != "first" || events[1].Message != "second" {
+ t.Fatalf("order = %q, %q; want first, second", events[0].Message, events[1].Message)
+ }
+}
+
+func TestReadEventsAppendOrderFallsBackToLineOrderWhenUnsequenced(t *testing.T) {
+ // Events written before sequence stamping still have to come back in append order.
+ tie := "2026-05-13T01:00:00Z"
+ earlier := testSchemaEvent(tie, "claude_code", "metric.observed", "metric", "")
+ earlier.Message = "line-1"
+ later := testSchemaEvent(tie, "claude_code", "metric.observed", "metric", "")
+ later.Message = "line-2"
+
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ writeTestLog(t, path, marshalEvents(t, earlier, later)...)
+
+ events, err := ReadEventsAppendOrder(path, EventQuery{})
+ if err != nil {
+ t.Fatalf("ReadEventsAppendOrder returned error: %v", err)
+ }
+ if len(events) != 2 {
+ t.Fatalf("read %d events, want 2", len(events))
+ }
+ if events[0].Message != "line-1" || events[1].Message != "line-2" {
+ t.Fatalf("order = %q, %q; want line-1, line-2", events[0].Message, events[1].Message)
+ }
+}
+
+func TestBuildSummaryPicksLastEventByInstantNotByString(t *testing.T) {
+ // A log spanning the move to nanosecond stamping: ":05Z" is the older event but sorts
+ // after ":05.500000000Z" byte-wise, because 'Z' outranks '.'.
+ older := testSchemaEvent("2026-05-13T01:00:05Z", "cursor", "tool.started", "tool", "")
+ newer := testSchemaEvent("2026-05-13T01:00:05.500000000Z", "cursor", "tool.completed", "tool", "")
+
+ summary := BuildSummary(EventResult{
+ TotalMatched: 2,
+ Events: []EventRecord{{Event: older}, {Event: newer}},
+ })
+ if summary.LastEventTime != newer.Timestamp {
+ t.Fatalf("LastEventTime = %q, want %q", summary.LastEventTime, newer.Timestamp)
+ }
+}
+
+func TestBuildSummarySkipsUnparseableTimestamps(t *testing.T) {
+ real := testSchemaEvent("2026-05-13T01:00:05.000000000Z", "cursor", "tool.started", "tool", "")
+ broken := testSchemaEvent("whenever", "cursor", "tool.completed", "tool", "")
+
+ summary := BuildSummary(EventResult{
+ TotalMatched: 2,
+ Events: []EventRecord{{Event: real}, {Event: broken}},
+ })
+ if summary.LastEventTime != real.Timestamp {
+ t.Fatalf("LastEventTime = %q, want %q", summary.LastEventTime, real.Timestamp)
+ }
+}
+
+func TestStreamEventsCarriesSequenceThrough(t *testing.T) {
+ // Detection reads the log through StreamEvents, so the ordering key has to survive
+ // the round trip to be of any use to the sort in front of the rules engine.
+ event := testSchemaEvent("2026-05-13T01:00:00.000000000Z", "claude_code", "command.executed", "command", "")
+ event.Sequence = 7
+
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ writeTestLog(t, path, marshalEvents(t, event)...)
+
+ var got []schema.Event
+ if err := StreamEvents(path, func(e schema.Event) error {
+ got = append(got, e)
+ return nil
+ }); err != nil {
+ t.Fatalf("StreamEvents returned error: %v", err)
+ }
+ if len(got) != 1 {
+ t.Fatalf("streamed %d events, want 1", len(got))
+ }
+ if got[0].Sequence != 7 {
+ t.Fatalf("sequence = %d, want 7", got[0].Sequence)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/dashboard/summary.go b/cli/beacon/internal/endpoint/dashboard/summary.go
index fbb2e7e2..497f2525 100644
--- a/cli/beacon/internal/endpoint/dashboard/summary.go
+++ b/cli/beacon/internal/endpoint/dashboard/summary.go
@@ -1,6 +1,11 @@
package dashboard
-import "sort"
+import (
+ "sort"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+)
type Count struct {
Name string `json:"name"`
@@ -53,10 +58,19 @@ func BuildSummary(result EventResult) Summary {
CountsByModel: map[string]int{},
}
sessions := map[string]bool{}
+ var lastEventAt time.Time
for _, record := range result.Events {
event := record.Event
- if summary.LastEventTime == "" || event.Timestamp > summary.LastEventTime {
- summary.LastEventTime = event.Timestamp
+ // Compared as instants rather than as strings. The two orderings agree only while
+ // every timestamp has the same width: in a log that spans the move to nanosecond
+ // stamping, ":05Z" sorts after ":05.500000000Z" byte-wise, because 'Z' outranks
+ // '.'. An unparseable timestamp is skipped rather than compared -- it cannot be
+ // the latest event if nothing can say when it happened.
+ if at, err := schema.ParseTimestamp(event.Timestamp); err == nil {
+ if summary.LastEventTime == "" || at.After(lastEventAt) {
+ summary.LastEventTime = event.Timestamp
+ lastEventAt = at
+ }
}
if event.Event.Action != "" {
summary.CountsByAction[event.Event.Action]++
diff --git a/cli/beacon/internal/endpoint/elastic/pack/component-template-mappings.json b/cli/beacon/internal/endpoint/elastic/pack/component-template-mappings.json
index 13edc775..92767beb 100644
--- a/cli/beacon/internal/endpoint/elastic/pack/component-template-mappings.json
+++ b/cli/beacon/internal/endpoint/elastic/pack/component-template-mappings.json
@@ -49,6 +49,7 @@
"vendor": { "type": "keyword" },
"product": { "type": "keyword" },
"schema_version": { "type": "keyword" },
+ "sequence": { "type": "long" },
"severity": { "type": "keyword" },
"truncated": { "type": "boolean" },
"harness": {
diff --git a/cli/beacon/internal/endpoint/elastic/pack/ingest-pipeline.json b/cli/beacon/internal/endpoint/elastic/pack/ingest-pipeline.json
index dfb0386b..94c79bf5 100644
--- a/cli/beacon/internal/endpoint/elastic/pack/ingest-pipeline.json
+++ b/cli/beacon/internal/endpoint/elastic/pack/ingest-pipeline.json
@@ -38,13 +38,14 @@
"script": {
"description": "Copy Beacon fields to ECS and preserve native fields under beacon.*",
"lang": "painless",
- "source": "Map ensure(Map parent, String key) { if (parent[key] == null || !(parent[key] instanceof Map)) { parent[key] = new HashMap(); } return parent[key]; } Map beacon = ensure(ctx, 'beacon'); if (ctx.vendor != null) { beacon.vendor = ctx.vendor; } if (ctx.product != null) { beacon.product = ctx.product; } if (ctx.schema_version != null) { beacon.schema_version = ctx.schema_version; } if (ctx.severity != null) { beacon.severity = ctx.severity; } if (ctx.field_truncated != null) { beacon.truncated = ctx.field_truncated; } Map agent = ensure(ctx, 'agent'); agent.name = 'beacon'; agent.type = 'endpoint-agent'; if (ctx.endpoint instanceof Map && ctx.endpoint.agent_version != null) { agent.version = ctx.endpoint.agent_version; } else if (ctx.schema_version != null) { agent.version = ctx.schema_version; } Map event = ensure(ctx, 'event'); event.kind = 'event'; if (ctx.event instanceof Map) { if (ctx.event.action != null) { event.action = ctx.event.action; } if (ctx.event.category != null) { event.category = [ctx.event.category.toString()]; } } if (ctx.severity != null) { Map sev = new HashMap(); sev.put('info', 2); sev.put('low', 3); sev.put('medium', 4); sev.put('high', 5); sev.put('critical', 6); String key = ctx.severity.toString().toLowerCase(); if (sev.containsKey(key)) { event.severity = sev[key]; } } if (ctx.endpoint instanceof Map) { Map host = ensure(ctx, 'host'); if (ctx.endpoint.hostname != null) { host.hostname = ctx.endpoint.hostname; host.name = ctx.endpoint.hostname; } if (ctx.endpoint.os != null) { Map os = ensure(host, 'os'); String osName = ctx.endpoint.os.toString(); os.family = osName; os.type = osName == 'darwin' ? 'macos' : osName; } } if (ctx.user instanceof Map) { Map user = ensure(ctx, 'user'); if (ctx.user.name != null) { user.name = ctx.user.name; } if (ctx.user.uid != null) { user.id = ctx.user.uid; } } if (ctx.harness instanceof Map) { Map harness = ensure(beacon, 'harness'); if (ctx.harness.name != null) { harness.name = ctx.harness.name; ensure(ctx, 'service').name = ctx.harness.name; } if (ctx.harness.version != null) { harness.version = ctx.harness.version; } if (ctx.harness.executable_path != null) { harness.executable_path = ctx.harness.executable_path; } if (ctx.harness.config_path != null) { harness.config_path = ctx.harness.config_path; } } if (ctx.session instanceof Map) { Map session = ensure(beacon, 'session'); if (ctx.session.id != null) { session.id = ctx.session.id; if (ctx.trace == null) { ctx.trace = new HashMap(); } if (ctx.trace.id == null && ctx.session.id.toString().length() == 32) { ctx.trace.id = ctx.session.id; } } if (ctx.session.working_directory != null) { ensure(ctx, 'process').working_directory = ctx.session.working_directory; } } if (ctx.tool instanceof Map) { Map tool = ensure(beacon, 'tool'); if (ctx.tool.name != null) { tool.name = ctx.tool.name; } Map process = ensure(ctx, 'process'); if (process.command_line == null && ctx.tool.command != null) { process.command_line = ctx.tool.command; } if (ctx.tool.path != null) { process.executable = ctx.tool.path; } } if (ctx.command instanceof Map) { Map process = ensure(ctx, 'process'); if (ctx.command.command != null) { process.command_line = ctx.command.command; } if (ctx.command.exit_code != null) { process.exit_code = ctx.command.exit_code; } if (ctx.command.duration_ms != null) { event.duration = ((long)ctx.command.duration_ms) * 1000000L; } } if (ctx.file instanceof Map) { Map file = ensure(ctx, 'file'); Map beaconFile = ensure(beacon, 'file'); if (ctx.file.path != null) { String p = ctx.file.path.toString(); file.path = p; int slash = p.lastIndexOf('/'); String name = slash >= 0 ? p.substring(slash + 1) : p; if (slash > 0) { file.directory = p.substring(0, slash); } file.name = name; int dot = name.lastIndexOf('.'); if (dot > 0 && dot < name.length() - 1) { file.extension = name.substring(dot + 1); } } if (ctx.file.diff_hash != null) { ensure(file, 'hash').sha256 = ctx.file.diff_hash; } if (ctx.file.diff_bytes != null) { file.size = ctx.file.diff_bytes; } if (ctx.file.operation != null) { beaconFile.operation = ctx.file.operation; } if (ctx.file.language != null) { beaconFile.language = ctx.file.language; } } if (ctx.mcp instanceof Map) { Map mcp = ensure(beacon, 'mcp'); if (ctx.mcp.server != null) { mcp.server = ctx.mcp.server; } if (ctx.mcp.tool != null) { mcp.tool = ctx.mcp.tool; } } if (ctx.approval instanceof Map) { Map approval = ensure(beacon, 'approval'); if (ctx.approval.required != null) { approval.required = ctx.approval.required; } if (ctx.approval.decision != null) { String decision = ctx.approval.decision.toString(); approval.decision = decision; if (decision == 'allow' || decision == 'approved') { event.outcome = 'success'; } else if (decision == 'deny' || decision == 'denied' || decision == 'block' || decision == 'blocked') { event.outcome = 'failure'; } } if (ctx.approval.reason != null) { approval.reason = ctx.approval.reason; } } if (ctx.policy instanceof Map) { Map policy = ensure(beacon, 'policy'); if (ctx.policy.id != null) { policy.id = ctx.policy.id; } if (ctx.policy.name != null) { policy.name = ctx.policy.name; } if (ctx.policy.decision != null) { policy.decision = ctx.policy.decision; } if (ctx.policy.enforcement != null) { policy.enforcement = ctx.policy.enforcement; } if (ctx.policy.reason != null) { policy.reason = ctx.policy.reason; } } if (ctx.prompt instanceof Map && ctx.prompt.text != null) { ensure(beacon, 'prompt').text = ctx.prompt.text; } if (ctx.content instanceof Map) { Map content = ensure(beacon, 'content'); if (ctx.content.retention != null) { content.retention = ctx.content.retention; } if (ctx.content.included != null) { content.included = ctx.content.included; } if (ctx.content.redacted != null) { content.redacted = ctx.content.redacted; } if (ctx.content.truncated != null) { content.truncated = ctx.content.truncated; } } if (ctx.destination instanceof Map) { Map destination = ensure(beacon, 'destination'); if (ctx.destination.type != null) { destination.type = ctx.destination.type; } if (ctx.destination.mode != null) { destination.mode = ctx.destination.mode; } if (ctx.destination.status != null) { destination.status = ctx.destination.status; } } if (ctx.health instanceof Map) { Map health = ensure(beacon, 'health'); if (ctx.health.component != null) { health.component = ctx.health.component; } if (ctx.health.status != null) { health.status = ctx.health.status; } if (ctx.health.reason != null) { health.reason = ctx.health.reason; } } if (ctx.model != null) { ensure(ensure(ctx, 'gen_ai'), 'request').model = ctx.model; } if (ctx.repository != null) { ensure(ensure(ctx, 'vcs'), 'repository').url = ctx.repository; } if (ctx.branch != null) { ensure(ensure(ensure(ctx, 'vcs'), 'ref'), 'head').name = ctx.branch; } if (ctx.raw instanceof Map) { Map otel = ensure(beacon, 'otel'); if (ctx.raw.otel_signal != null) { otel.signal = ctx.raw.otel_signal; } if (ctx.raw.metric_name != null) { ensure(beacon, 'metric').name = ctx.raw.metric_name; if (event.action == null || event.action == 'metric.observed') { event.action = ctx.raw.metric_name; } } if (ctx.raw.metric_description != null) { otel.metric_description = ctx.raw.metric_description; } if (ctx.raw.metric_unit != null) { otel.metric_unit = ctx.raw.metric_unit; } if (ctx.raw.attribute_count != null) { otel.attribute_count = ctx.raw.attribute_count; } if (ctx.raw.attributes != null) { otel.attributes = ctx.raw.attributes; } }"
+ "source": "Map ensure(Map parent, String key) { if (parent[key] == null || !(parent[key] instanceof Map)) { parent[key] = new HashMap(); } return parent[key]; } Map beacon = ensure(ctx, 'beacon'); if (ctx.vendor != null) { beacon.vendor = ctx.vendor; } if (ctx.product != null) { beacon.product = ctx.product; } if (ctx.schema_version != null) { beacon.schema_version = ctx.schema_version; } if (ctx.sequence != null) { beacon.sequence = ctx.sequence; } if (ctx.severity != null) { beacon.severity = ctx.severity; } if (ctx.field_truncated != null) { beacon.truncated = ctx.field_truncated; } Map agent = ensure(ctx, 'agent'); agent.name = 'beacon'; agent.type = 'endpoint-agent'; if (ctx.endpoint instanceof Map && ctx.endpoint.agent_version != null) { agent.version = ctx.endpoint.agent_version; } else if (ctx.schema_version != null) { agent.version = ctx.schema_version; } Map event = ensure(ctx, 'event'); event.kind = 'event'; if (ctx.event instanceof Map) { if (ctx.event.action != null) { event.action = ctx.event.action; } if (ctx.event.category != null) { event.category = [ctx.event.category.toString()]; } } if (ctx.severity != null) { Map sev = new HashMap(); sev.put('info', 2); sev.put('low', 3); sev.put('medium', 4); sev.put('high', 5); sev.put('critical', 6); String key = ctx.severity.toString().toLowerCase(); if (sev.containsKey(key)) { event.severity = sev[key]; } } if (ctx.endpoint instanceof Map) { Map host = ensure(ctx, 'host'); if (ctx.endpoint.hostname != null) { host.hostname = ctx.endpoint.hostname; host.name = ctx.endpoint.hostname; } if (ctx.endpoint.os != null) { Map os = ensure(host, 'os'); String osName = ctx.endpoint.os.toString(); os.family = osName; os.type = osName == 'darwin' ? 'macos' : osName; } } if (ctx.user instanceof Map) { Map user = ensure(ctx, 'user'); if (ctx.user.name != null) { user.name = ctx.user.name; } if (ctx.user.uid != null) { user.id = ctx.user.uid; } } if (ctx.harness instanceof Map) { Map harness = ensure(beacon, 'harness'); if (ctx.harness.name != null) { harness.name = ctx.harness.name; ensure(ctx, 'service').name = ctx.harness.name; } if (ctx.harness.version != null) { harness.version = ctx.harness.version; } if (ctx.harness.executable_path != null) { harness.executable_path = ctx.harness.executable_path; } if (ctx.harness.config_path != null) { harness.config_path = ctx.harness.config_path; } } if (ctx.session instanceof Map) { Map session = ensure(beacon, 'session'); if (ctx.session.id != null) { session.id = ctx.session.id; if (ctx.trace == null) { ctx.trace = new HashMap(); } if (ctx.trace.id == null && ctx.session.id.toString().length() == 32) { ctx.trace.id = ctx.session.id; } } if (ctx.session.working_directory != null) { ensure(ctx, 'process').working_directory = ctx.session.working_directory; } } if (ctx.tool instanceof Map) { Map tool = ensure(beacon, 'tool'); if (ctx.tool.name != null) { tool.name = ctx.tool.name; } Map process = ensure(ctx, 'process'); if (process.command_line == null && ctx.tool.command != null) { process.command_line = ctx.tool.command; } if (ctx.tool.path != null) { process.executable = ctx.tool.path; } } if (ctx.command instanceof Map) { Map process = ensure(ctx, 'process'); if (ctx.command.command != null) { process.command_line = ctx.command.command; } if (ctx.command.exit_code != null) { process.exit_code = ctx.command.exit_code; } if (ctx.command.duration_ms != null) { event.duration = ((long)ctx.command.duration_ms) * 1000000L; } } if (ctx.file instanceof Map) { Map file = ensure(ctx, 'file'); Map beaconFile = ensure(beacon, 'file'); if (ctx.file.path != null) { String p = ctx.file.path.toString(); file.path = p; int slash = p.lastIndexOf('/'); String name = slash >= 0 ? p.substring(slash + 1) : p; if (slash > 0) { file.directory = p.substring(0, slash); } file.name = name; int dot = name.lastIndexOf('.'); if (dot > 0 && dot < name.length() - 1) { file.extension = name.substring(dot + 1); } } if (ctx.file.diff_hash != null) { ensure(file, 'hash').sha256 = ctx.file.diff_hash; } if (ctx.file.diff_bytes != null) { file.size = ctx.file.diff_bytes; } if (ctx.file.operation != null) { beaconFile.operation = ctx.file.operation; } if (ctx.file.language != null) { beaconFile.language = ctx.file.language; } } if (ctx.mcp instanceof Map) { Map mcp = ensure(beacon, 'mcp'); if (ctx.mcp.server != null) { mcp.server = ctx.mcp.server; } if (ctx.mcp.tool != null) { mcp.tool = ctx.mcp.tool; } } if (ctx.approval instanceof Map) { Map approval = ensure(beacon, 'approval'); if (ctx.approval.required != null) { approval.required = ctx.approval.required; } if (ctx.approval.decision != null) { String decision = ctx.approval.decision.toString(); approval.decision = decision; if (decision == 'allow' || decision == 'approved') { event.outcome = 'success'; } else if (decision == 'deny' || decision == 'denied' || decision == 'block' || decision == 'blocked') { event.outcome = 'failure'; } } if (ctx.approval.reason != null) { approval.reason = ctx.approval.reason; } } if (ctx.policy instanceof Map) { Map policy = ensure(beacon, 'policy'); if (ctx.policy.id != null) { policy.id = ctx.policy.id; } if (ctx.policy.name != null) { policy.name = ctx.policy.name; } if (ctx.policy.decision != null) { policy.decision = ctx.policy.decision; } if (ctx.policy.enforcement != null) { policy.enforcement = ctx.policy.enforcement; } if (ctx.policy.reason != null) { policy.reason = ctx.policy.reason; } } if (ctx.prompt instanceof Map && ctx.prompt.text != null) { ensure(beacon, 'prompt').text = ctx.prompt.text; } if (ctx.content instanceof Map) { Map content = ensure(beacon, 'content'); if (ctx.content.retention != null) { content.retention = ctx.content.retention; } if (ctx.content.included != null) { content.included = ctx.content.included; } if (ctx.content.redacted != null) { content.redacted = ctx.content.redacted; } if (ctx.content.truncated != null) { content.truncated = ctx.content.truncated; } } if (ctx.destination instanceof Map) { Map destination = ensure(beacon, 'destination'); if (ctx.destination.type != null) { destination.type = ctx.destination.type; } if (ctx.destination.mode != null) { destination.mode = ctx.destination.mode; } if (ctx.destination.status != null) { destination.status = ctx.destination.status; } } if (ctx.health instanceof Map) { Map health = ensure(beacon, 'health'); if (ctx.health.component != null) { health.component = ctx.health.component; } if (ctx.health.status != null) { health.status = ctx.health.status; } if (ctx.health.reason != null) { health.reason = ctx.health.reason; } } if (ctx.model != null) { ensure(ensure(ctx, 'gen_ai'), 'request').model = ctx.model; } if (ctx.repository != null) { ensure(ensure(ctx, 'vcs'), 'repository').url = ctx.repository; } if (ctx.branch != null) { ensure(ensure(ensure(ctx, 'vcs'), 'ref'), 'head').name = ctx.branch; } if (ctx.raw instanceof Map) { Map otel = ensure(beacon, 'otel'); if (ctx.raw.otel_signal != null) { otel.signal = ctx.raw.otel_signal; } if (ctx.raw.metric_name != null) { ensure(beacon, 'metric').name = ctx.raw.metric_name; if (event.action == null || event.action == 'metric.observed') { event.action = ctx.raw.metric_name; } } if (ctx.raw.metric_description != null) { otel.metric_description = ctx.raw.metric_description; } if (ctx.raw.metric_unit != null) { otel.metric_unit = ctx.raw.metric_unit; } if (ctx.raw.attribute_count != null) { otel.attribute_count = ctx.raw.attribute_count; } if (ctx.raw.attributes != null) { otel.attributes = ctx.raw.attributes; } }"
}
},
{
"remove": {
"field": [
"timestamp",
+ "sequence",
"vendor",
"product",
"schema_version",
diff --git a/cli/beacon/internal/endpoint/schema/event.go b/cli/beacon/internal/endpoint/schema/event.go
index 3f4217be..87bc6c8f 100644
--- a/cli/beacon/internal/endpoint/schema/event.go
+++ b/cli/beacon/internal/endpoint/schema/event.go
@@ -8,6 +8,16 @@ const (
SchemaVersion = asymptoteobserve.SchemaVersion
)
+// TimestampFormat, FormatTimestamp and ParseTimestamp are the canonical event
+// timestamp layout and its reader/writer. Re-exported so nothing in the CLI has to
+// hand-roll a layout string and drift from what the writers emit.
+const TimestampFormat = asymptoteobserve.TimestampFormat
+
+var (
+ FormatTimestamp = asymptoteobserve.FormatTimestamp
+ ParseTimestamp = asymptoteobserve.ParseTimestamp
+)
+
type Severity = asymptoteobserve.Severity
const (
diff --git a/cli/beacon/internal/tokens/tokens.go b/cli/beacon/internal/tokens/tokens.go
index 73ed81f8..00785497 100644
--- a/cli/beacon/internal/tokens/tokens.go
+++ b/cli/beacon/internal/tokens/tokens.go
@@ -235,7 +235,7 @@ func collectUsageEvents(events []schema.Event) []*usageEvent {
repository: event.Repository,
usage: Usage{Events: 1},
}
- if ts, err := time.Parse(time.RFC3339, event.Timestamp); err == nil {
+ if ts, err := schema.ParseTimestamp(event.Timestamp); err == nil {
ue.ts = ts
}
if event.Session != nil {
@@ -586,7 +586,7 @@ func buildSessionDetail(events []*usageEvent, sessionID string) *SessionDetail {
Usage: ue.usage,
}
if !ue.ts.IsZero() {
- step.Timestamp = ue.ts.UTC().Format(time.RFC3339)
+ step.Timestamp = schema.FormatTimestamp(ue.ts)
}
steps = append(steps, step)
if step.SpanID != "" {
diff --git a/collector-builder/exporter/beaconjsonexporter/exporter.go b/collector-builder/exporter/beaconjsonexporter/exporter.go
index 74be3c60..668735c8 100644
--- a/collector-builder/exporter/beaconjsonexporter/exporter.go
+++ b/collector-builder/exporter/beaconjsonexporter/exporter.go
@@ -14,6 +14,7 @@ import (
"go.uber.org/zap"
"github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/internal/beaconevent"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
type beaconExporter struct {
@@ -21,6 +22,12 @@ type beaconExporter struct {
writer jsonlWriter
logger *zap.Logger
converter beaconevent.Converter
+ // sequence numbers the events this exporter writes, in the order it walks them off
+ // the wire. Nanosecond timestamps order almost everything on their own, but one
+ // metric export flushes a batch of datapoints that all carry the same collection
+ // instant; the counter is what recovers their emission order without falling back
+ // to where the lines landed in the file.
+ sequence *asymptoteobserve.Sequencer
}
const (
@@ -56,7 +63,8 @@ func newExporter(raw component.Config, set exporter.Settings) (*beaconExporter,
rotateArchives: cfg.RotateArchives,
redactSecrets: cfg.RedactSecrets,
},
- logger: set.Logger,
+ logger: set.Logger,
+ sequence: &asymptoteobserve.Sequencer{},
converter: beaconevent.NewConverter(beaconevent.Options{
IncludeRuntimeMetrics: cfg.IncludeRuntimeMetrics,
IncludeCodexSpans: cfg.IncludeCodexSpans,
@@ -68,6 +76,7 @@ func (e *beaconExporter) consumeLogs(ctx context.Context, logs plog.Logs) error
_ = ctx
var firstErr error
for _, event := range e.eventConverter().EventsFromLogs(logs) {
+ e.stampSequence(&event)
if err := e.writer.append(event); err != nil && firstErr == nil {
firstErr = err
}
@@ -79,6 +88,7 @@ func (e *beaconExporter) consumeTraces(ctx context.Context, traces ptrace.Traces
_ = ctx
var firstErr error
for _, event := range e.eventConverter().EventsFromTraces(traces) {
+ e.stampSequence(&event)
if err := e.writer.append(event); err != nil && firstErr == nil {
firstErr = err
}
@@ -90,6 +100,7 @@ func (e *beaconExporter) consumeMetrics(ctx context.Context, metrics pmetric.Met
_ = ctx
var firstErr error
for _, event := range e.eventConverter().EventsFromMetrics(metrics) {
+ e.stampSequence(&event)
if err := e.writer.append(event); err != nil && firstErr == nil {
firstErr = err
}
@@ -97,6 +108,15 @@ func (e *beaconExporter) consumeMetrics(ctx context.Context, metrics pmetric.Met
return firstErr
}
+// stampSequence gives the event this exporter's next emission number, unless the runtime
+// already supplied one of its own on the wire and the converter promoted it.
+func (e *beaconExporter) stampSequence(event *beaconEvent) {
+ if event.Sequence != 0 {
+ return
+ }
+ event.Sequence = e.sequence.Next()
+}
+
func shouldDropLog(resourceAttrs map[string]interface{}, record plog.LogRecord) bool {
return beaconevent.ShouldDropLog(resourceAttrs, record)
}
diff --git a/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go
index bfd23c91..59ffb249 100644
--- a/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go
+++ b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go
@@ -22,6 +22,7 @@ import (
"go.uber.org/zap"
"github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/internal/beaconevent"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
type falconExporter struct {
@@ -170,7 +171,7 @@ func eventTime(event beaconevent.Event) (time.Time, error) {
if event.Timestamp == "" {
return time.Now().UTC(), nil
}
- ts, err := time.Parse(time.RFC3339Nano, event.Timestamp)
+ ts, err := asymptoteobserve.ParseTimestamp(event.Timestamp)
if err != nil {
return time.Time{}, err
}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
index 1522b3d5..e302c8f2 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
@@ -815,6 +815,13 @@ func ApplyTokenUsage(event *Event, tokenType string, value int64) {
func (c Converter) PopulateCommon(event *Event, attrs map[string]interface{}) {
populateRunContext(event, attrs)
+ // A runtime that numbers its own telemetry gets that number preserved; the exporter
+ // stamps its own emission counter for everything else (see beaconExporter.
+ // stampSequence). Zero and negative values are ignored -- zero is the schema's
+ // "unsequenced" and a negative counter is not one.
+ if sequence, ok := Int64Attr(attrs, "beacon.event.sequence", "event.sequence"); ok && sequence > 0 {
+ event.Sequence = uint64(sequence)
+ }
event.GenAI = GenAIFromAttrs(attrs)
event.Model = FirstString(attrs, "gen_ai.request.model", "gen_ai.response.model", "model", "ai.model")
event.Repository = FirstString(attrs, "vcs.repository.url", "repository", "repo.path", "workspace.repository")
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
index 2d5c7a02..b50433ec 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
@@ -65,8 +65,13 @@ type GenAIUsageReasoningInfo = asymptoteobserve.GenAIUsageReasoningInfo
type GenAIWorkflowInfo = asymptoteobserve.GenAIWorkflowInfo
type Event struct {
- ObservedAt time.Time `json:"-"`
- Timestamp string `json:"timestamp"`
+ ObservedAt time.Time `json:"-"`
+ Timestamp string `json:"timestamp"`
+ // Sequence mirrors asymptoteobserve.Event.Sequence: the exporter's monotonic emission
+ // counter, stamped in wire order as records are walked. It is what still separates the
+ // datapoints of one metric export, which all carry that export's collection instant
+ // and so tie on the timestamp no matter how precise the timestamp gets.
+ Sequence uint64 `json:"sequence,omitempty"`
Vendor string `json:"vendor"`
Product string `json:"product"`
SchemaVersion string `json:"schema_version"`
@@ -121,7 +126,7 @@ func NewEvent(action, category, severity, harnessName string, ts time.Time) Even
})
return Event{
ObservedAt: ts.UTC(),
- Timestamp: ts.UTC().Format(time.RFC3339),
+ Timestamp: asymptoteobserve.FormatTimestamp(ts),
Vendor: base.Vendor,
Product: base.Product,
SchemaVersion: base.SchemaVersion,
diff --git a/collector-builder/exporter/beaconjsonexporter/ordering_test.go b/collector-builder/exporter/beaconjsonexporter/ordering_test.go
new file mode 100644
index 00000000..e355225b
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/ordering_test.go
@@ -0,0 +1,218 @@
+package beaconjsonexporter
+
+import (
+ "context"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "go.opentelemetry.io/collector/exporter"
+ "go.opentelemetry.io/collector/pdata/pcommon"
+ "go.opentelemetry.io/collector/pdata/plog"
+ "go.opentelemetry.io/collector/pdata/pmetric"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// orderingExporter builds an exporter writing to a fresh runtime log, and returns it with
+// the log path.
+func orderingExporter(t *testing.T) (*beaconExporter, string) {
+ t.Helper()
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ exp, err := newExporter(&Config{
+ Path: path,
+ MaxEventBytes: defaultMaxEventBytes,
+ RotateBytes: defaultRotateBytes,
+ RedactSecrets: true,
+ IncludeRuntimeMetrics: true,
+ }, exporter.Settings{})
+ if err != nil {
+ t.Fatalf("newExporter returned error: %v", err)
+ }
+ return exp, path
+}
+
+// writtenEvents decodes the events the exporter wrote, in file order.
+func writtenEvents(t *testing.T, path string) []asymptoteobserve.Event {
+ t.Helper()
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read %s: %v", path, err)
+ }
+ var events []asymptoteobserve.Event
+ for _, line := range strings.Split(strings.TrimSpace(string(data)), "\n") {
+ if line == "" {
+ continue
+ }
+ var event asymptoteobserve.Event
+ if err := json.Unmarshal([]byte(line), &event); err != nil {
+ t.Fatalf("decode %q: %v", line, err)
+ }
+ events = append(events, event)
+ }
+ if len(events) == 0 {
+ t.Fatalf("no events written to %s", path)
+ }
+ return events
+}
+
+// promptLogs builds a batch of prompt log records at the given times.
+func promptLogs(times ...time.Time) plog.Logs {
+ logs := plog.NewLogs()
+ records := logs.ResourceLogs().AppendEmpty().ScopeLogs().AppendEmpty().LogRecords()
+ for i, at := range times {
+ record := records.AppendEmpty()
+ record.SetTimestamp(pcommon.NewTimestampFromTime(at))
+ record.Attributes().PutStr("beacon.event.action", "prompt.submitted")
+ record.Attributes().PutStr("gen_ai.prompt", string(rune('a'+i)))
+ }
+ return logs
+}
+
+func TestConsumeLogsKeepsWireNanosecondPrecision(t *testing.T) {
+ // The exporter already received nanosecond timestamps off the wire and threw the
+ // sub-second part away formatting them, which is why no event in a real runtime log
+ // carried one.
+ exp, path := orderingExporter(t)
+ at := time.Date(2026, 8, 21, 9, 14, 3, 123456789, time.UTC)
+ if err := exp.consumeLogs(context.Background(), promptLogs(at)); err != nil {
+ t.Fatalf("consumeLogs returned error: %v", err)
+ }
+
+ event := writtenEvents(t, path)[0]
+ if want := asymptoteobserve.FormatTimestamp(at); event.Timestamp != want {
+ t.Fatalf("timestamp = %q, want %q", event.Timestamp, want)
+ }
+}
+
+func TestConsumeLogsStampsSequenceInWireOrder(t *testing.T) {
+ exp, path := orderingExporter(t)
+ base := time.Date(2026, 8, 21, 9, 14, 3, 0, time.UTC)
+ logs := promptLogs(base, base.Add(time.Millisecond), base.Add(2*time.Millisecond))
+ if err := exp.consumeLogs(context.Background(), logs); err != nil {
+ t.Fatalf("consumeLogs returned error: %v", err)
+ }
+
+ events := writtenEvents(t, path)
+ if len(events) != 3 {
+ t.Fatalf("wrote %d events, want 3", len(events))
+ }
+ for i, event := range events {
+ if want := uint64(i + 1); event.Sequence != want {
+ t.Fatalf("event %d sequence = %d, want %d", i, event.Sequence, want)
+ }
+ }
+}
+
+func TestSequenceContinuesAcrossExports(t *testing.T) {
+ // One counter for the exporter's lifetime, so two batches never claim the same
+ // number and the second export cannot look like it came first.
+ exp, path := orderingExporter(t)
+ base := time.Date(2026, 8, 21, 9, 14, 3, 0, time.UTC)
+ if err := exp.consumeLogs(context.Background(), promptLogs(base)); err != nil {
+ t.Fatalf("first consumeLogs returned error: %v", err)
+ }
+ if err := exp.consumeLogs(context.Background(), promptLogs(base.Add(time.Second))); err != nil {
+ t.Fatalf("second consumeLogs returned error: %v", err)
+ }
+
+ events := writtenEvents(t, path)
+ if len(events) != 2 {
+ t.Fatalf("wrote %d events, want 2", len(events))
+ }
+ if events[0].Sequence != 1 || events[1].Sequence != 2 {
+ t.Fatalf("sequences = %d, %d; want 1, 2", events[0].Sequence, events[1].Sequence)
+ }
+}
+
+func TestConsumeMetricsSeparatesDatapointsSharingATimestamp(t *testing.T) {
+ // The case a more precise timestamp cannot fix: one export flushes a batch of
+ // datapoints that all carry that export's collection instant. Token attribution
+ // depends on recovering their emission order.
+ exp, path := orderingExporter(t)
+ at := pcommon.NewTimestampFromTime(time.Date(2026, 8, 21, 9, 14, 3, 500000000, time.UTC))
+
+ metrics := pmetric.NewMetrics()
+ metric := metrics.ResourceMetrics().AppendEmpty().ScopeMetrics().AppendEmpty().Metrics().AppendEmpty()
+ metric.SetName("claude_code.token.usage")
+ sum := metric.SetEmptySum()
+ for _, tokenType := range []string{"input", "output", "cacheRead"} {
+ point := sum.DataPoints().AppendEmpty()
+ point.SetTimestamp(at)
+ point.SetIntValue(10)
+ point.Attributes().PutStr("type", tokenType)
+ }
+
+ if err := exp.consumeMetrics(context.Background(), metrics); err != nil {
+ t.Fatalf("consumeMetrics returned error: %v", err)
+ }
+
+ events := writtenEvents(t, path)
+ if len(events) != 3 {
+ t.Fatalf("wrote %d events, want one per datapoint", len(events))
+ }
+ stamp := events[0].Timestamp
+ for i, event := range events {
+ if event.Timestamp != stamp {
+ t.Fatalf("event %d timestamp = %q, want the shared %q (the premise of this test)",
+ i, event.Timestamp, stamp)
+ }
+ if want := uint64(i + 1); event.Sequence != want {
+ t.Fatalf("event %d sequence = %d, want %d", i, event.Sequence, want)
+ }
+ }
+}
+
+func TestConsumeLogsPromotesRuntimeSuppliedSequence(t *testing.T) {
+ // A runtime that numbers its own telemetry keeps its numbering; the exporter only
+ // fills in what nobody counted.
+ exp, path := orderingExporter(t)
+ logs := plog.NewLogs()
+ records := logs.ResourceLogs().AppendEmpty().ScopeLogs().AppendEmpty().LogRecords()
+
+ supplied := records.AppendEmpty()
+ supplied.SetTimestamp(pcommon.NewTimestampFromTime(time.Date(2026, 8, 21, 9, 14, 3, 0, time.UTC)))
+ supplied.Attributes().PutStr("beacon.event.action", "prompt.submitted")
+ supplied.Attributes().PutInt("event.sequence", 4096)
+
+ unsupplied := records.AppendEmpty()
+ unsupplied.SetTimestamp(pcommon.NewTimestampFromTime(time.Date(2026, 8, 21, 9, 14, 4, 0, time.UTC)))
+ unsupplied.Attributes().PutStr("beacon.event.action", "prompt.submitted")
+
+ if err := exp.consumeLogs(context.Background(), logs); err != nil {
+ t.Fatalf("consumeLogs returned error: %v", err)
+ }
+
+ events := writtenEvents(t, path)
+ if len(events) != 2 {
+ t.Fatalf("wrote %d events, want 2", len(events))
+ }
+ if events[0].Sequence != 4096 {
+ t.Fatalf("supplied sequence = %d, want 4096 preserved", events[0].Sequence)
+ }
+ if events[1].Sequence != 1 {
+ t.Fatalf("stamped sequence = %d, want 1 (the exporter's own counter is untouched by the promoted one)", events[1].Sequence)
+ }
+}
+
+func TestPromotedSequenceRejectsNonPositiveValues(t *testing.T) {
+ // Zero is the schema's "unsequenced" and a negative counter is not a counter, so
+ // neither may displace the exporter's own number.
+ exp, _ := orderingExporter(t)
+ for _, supplied := range []int64{0, -7} {
+ record := plog.NewLogs().ResourceLogs().AppendEmpty().ScopeLogs().AppendEmpty().LogRecords().AppendEmpty()
+ record.Attributes().PutStr("beacon.event.action", "prompt.submitted")
+ record.Attributes().PutInt("event.sequence", supplied)
+ event := exp.eventFromLog(nil, record)
+ if event.Sequence != 0 {
+ t.Fatalf("event.sequence=%d promoted to %d, want left unsequenced", supplied, event.Sequence)
+ }
+ exp.stampSequence(&event)
+ if event.Sequence == 0 {
+ t.Fatalf("event.sequence=%d left unstamped by the exporter", supplied)
+ }
+ }
+}
diff --git a/docs/detections/engine.mdx b/docs/detections/engine.mdx
index 3e7471b4..bceee589 100644
--- a/docs/detections/engine.mdx
+++ b/docs/detections/engine.mdx
@@ -79,6 +79,12 @@ For `threat-rules/v1`, correlation scope is `session`. Beacon groups events by `
Correlation is useful when no single event is suspicious enough on its own, but the sequence is meaningful.
+"In order" means the order the events happened, not the order they were written. `beacon
+scan` sorts the runtime log by `(timestamp, sequence)` before evaluating, because append
+order is not emission order — a hook writes the moment it intercepts a tool call, while the
+collector exporter writes on its export interval. See [event
+ordering](/telemetry-schema/event-schema#event-ordering).
+
## Findings
When a rule fires, Beacon emits a finding. Findings include:
diff --git a/docs/log-forwarding/falcon.mdx b/docs/log-forwarding/falcon.mdx
index 716c34fd..292136b8 100644
--- a/docs/log-forwarding/falcon.mdx
+++ b/docs/log-forwarding/falcon.mdx
@@ -58,7 +58,7 @@ Parses Beacon endpoint telemetry where each log line is one JSON object.
| observer.type := "endpoint"
| parseJson(prefix="Vendor.", excludeEmpty="true", handleNull="discard")
| Vendor.timestamp := Vendor.timestamp
-| parseTimestamp(field="Vendor.timestamp", format="yyyy-MM-dd'T'HH:mm:ss[.SSS]XXX", timezone="UTC")
+| parseTimestamp(field="Vendor.timestamp", format="yyyy-MM-dd'T'HH:mm:ss[.SSSSSSSSS]XXX", timezone="UTC")
| event.kind := "event"
| event.action := Vendor.event.action
| event.module := Vendor.product
diff --git a/docs/telemetry-schema/event-schema.mdx b/docs/telemetry-schema/event-schema.mdx
index 007e72a3..35b5df47 100644
--- a/docs/telemetry-schema/event-schema.mdx
+++ b/docs/telemetry-schema/event-schema.mdx
@@ -26,7 +26,7 @@ The schema gives every event a consistent backbone:
| Field | Meaning |
|-------|---------|
-| `timestamp` | UTC event time |
+| `timestamp` | UTC event time, RFC3339 with nanosecond precision (`2026-08-21T09:14:03.123456789Z`) |
| `vendor` | Always `beacon` |
| `product` | Current product identifier, `endpoint-agent` |
| `schema_version` | Current public schema version, `1.0` |
@@ -37,6 +37,29 @@ The schema gives every event a consistent backbone:
| `endpoint` | Host and operating system context |
| `harness` | Runtime that produced the signal |
+## Event ordering
+
+Two events can only be reasoned about together if you can tell which came first, so the
+schema carries two ordering fields.
+
+| Field | Meaning |
+|-------|---------|
+| `timestamp` | The cross-source ordering key. Both capture paths stamp it from the same clock at nanosecond precision and at a fixed width, so two UTC timestamps compare the same way as strings and as instants. |
+| `sequence` | Optional. The emitting writer's monotonic emission counter for the event, starting at 1; absent means unsequenced. It breaks ties between events that share a timestamp. |
+
+`sequence` numbers one writer's stream, not the log as a whole. The hook adapter runs as a
+fresh short-lived process per hook and the collector exporter runs as one long-lived export
+loop, so neither can see the other's counter, and a hook event numbered 1 may well have
+happened after an exporter event numbered 900. Order by `timestamp` first and use
+`sequence` only to separate events that tie on it — most often the datapoints of a single
+metric export, which all carry that export's collection instant.
+
+Do not order events by their position in the log. Append order is not emission order: a
+hook writes synchronously the moment it intercepts a tool call, while the exporter writes
+on its export interval, so an event that happened earlier routinely lands in the file
+later. `beacon scan` and the dashboard's detection view sort the log by `(timestamp,
+sequence)` before evaluating correlation rules for exactly this reason.
+
## How it extends OpenTelemetry
Beacon accepts OpenTelemetry attributes, including the GenAI semantic conventions, and projects them into fields that are easier to query across agent runtimes. OpenTelemetry context is preserved under `gen_ai` where available, while commonly investigated values are also normalized into Beacon fields such as `model`, `tool.name`, `prompt.text`, `command.command`, `file.path`, and `gen_ai.usage`.
diff --git a/docs/telemetry-schema/examples.mdx b/docs/telemetry-schema/examples.mdx
index 68886b30..98b4920c 100644
--- a/docs/telemetry-schema/examples.mdx
+++ b/docs/telemetry-schema/examples.mdx
@@ -11,7 +11,8 @@ Beacon writes events as JSONL records. Each line is a complete JSON object that
```json
{
- "timestamp": "2026-05-11T22:21:00Z",
+ "timestamp": "2026-05-11T22:21:00.418302511Z",
+ "sequence": 12,
"vendor": "beacon",
"product": "endpoint-agent",
"schema_version": "1.0",
@@ -51,7 +52,7 @@ Beacon writes events as JSONL records. Each line is a complete JSON object that
```json
{
- "timestamp": "2026-06-08T12:12:00Z",
+ "timestamp": "2026-06-08T12:12:00.907441238Z",
"vendor": "beacon",
"product": "endpoint-agent",
"schema_version": "1.0",
diff --git a/docs/telemetry-schema/fields.mdx b/docs/telemetry-schema/fields.mdx
index 365f770d..67ea128c 100644
--- a/docs/telemetry-schema/fields.mdx
+++ b/docs/telemetry-schema/fields.mdx
@@ -34,7 +34,9 @@ Beacon models each event as an action plus a set of typed entities. The [`event`
| `destination` | Output or validation destination state | `type`, `mode`, `status` |
| `health` | Endpoint or component health state | `component`, `status`, `reason` |
-Top-level `model`, `repository`, `branch`, `message`, `raw`, and `field_truncated` fields add shared context that can apply across multiple entities. For example, a command event can include both `tool` and `command`; a file edit can include `file`, `session`, `repository`, and `branch`; a CI event can include `origin` and `run`; and a GenAI tool call can include both `tool` and nested `gen_ai.tool` metadata.
+Top-level `sequence`, `model`, `repository`, `branch`, `message`, `raw`, and `field_truncated` fields add shared context that can apply across multiple entities. For example, a command event can include both `tool` and `command`; a file edit can include `file`, `session`, `repository`, and `branch`; a CI event can include `origin` and `run`; and a GenAI tool call can include both `tool` and nested `gen_ai.tool` metadata.
+
+`sequence` is the emitting writer's monotonic emission counter, used to order events that share a timestamp. See [event ordering](/telemetry-schema/event-schema#event-ordering) for what it does and does not compare across.
For hook-based runtimes, when the runtime payload does not supply a branch, Beacon fills `branch` from the working directory's git checkout by reading `.git/HEAD` directly — no git binary is required, and the field is omitted when the directory is not a git repository or HEAD is detached. Set `BEACON_DISABLE_GIT_METADATA=1` (accepts `1`, `true`, or `yes`) in the runtime's environment to turn off local git metadata enrichment; runtime-provided branch values still pass through.
diff --git a/pkg/asymptoteobserve/dedupe.go b/pkg/asymptoteobserve/dedupe.go
index 7a1e5a72..ff43ca61 100644
--- a/pkg/asymptoteobserve/dedupe.go
+++ b/pkg/asymptoteobserve/dedupe.go
@@ -101,7 +101,7 @@ func endpointDedupeCandidate(line []byte) (endpointDedupeEvent, bool) {
if sessionID == "" {
return endpointDedupeEvent{}, false
}
- ts, err := time.Parse(time.RFC3339Nano, stringValue(event["timestamp"]))
+ ts, err := ParseTimestamp(stringValue(event["timestamp"]))
if err != nil || ts.IsZero() {
return endpointDedupeEvent{}, false
}
diff --git a/pkg/asymptoteobserve/event.go b/pkg/asymptoteobserve/event.go
index a3934819..91faa511 100644
--- a/pkg/asymptoteobserve/event.go
+++ b/pkg/asymptoteobserve/event.go
@@ -382,7 +382,19 @@ type ServerInfo struct {
}
type Event struct {
- Timestamp string `json:"timestamp"`
+ Timestamp string `json:"timestamp"`
+ // Sequence is the emitting writer's monotonic emission counter for this event,
+ // starting at 1; 0 means unsequenced. It breaks ties between events that share a
+ // timestamp -- routine while stamping was second-resolution, and still possible
+ // afterwards because one metric export flushes a batch of datapoints that all carry
+ // the same collection instant.
+ //
+ // It orders one writer's stream, not the log as a whole: the hook adapter runs as a
+ // fresh short-lived process per hook and the collector runs as one long-lived export
+ // loop, so neither can see the other's counter. Timestamp is the cross-writer
+ // ordering key and Sequence is the tiebreaker beneath it -- see
+ // threatrules.SortEvents, which is how correlation gets its ordered input.
+ Sequence uint64 `json:"sequence,omitempty"`
Vendor string `json:"vendor"`
Product string `json:"product"`
SchemaVersion string `json:"schema_version"`
@@ -441,7 +453,7 @@ func NewEvent(opts NewEventOptions) Event {
severity = SeverityInfo
}
return Event{
- Timestamp: time.Now().UTC().Format(time.RFC3339),
+ Timestamp: FormatTimestamp(time.Now()),
Vendor: Vendor,
Product: Product,
SchemaVersion: SchemaVersion,
diff --git a/pkg/asymptoteobserve/ordering.go b/pkg/asymptoteobserve/ordering.go
new file mode 100644
index 00000000..e18a3e0e
--- /dev/null
+++ b/pkg/asymptoteobserve/ordering.go
@@ -0,0 +1,46 @@
+package asymptoteobserve
+
+import (
+ "sync/atomic"
+ "time"
+)
+
+// TimestampFormat is the canonical layout for a Beacon event timestamp: RFC3339 in UTC
+// with fixed-width nanoseconds.
+//
+// It is deliberately not time.RFC3339Nano. That layout trims trailing zeros from the
+// fractional second, so the same clock renders at three different widths depending on the
+// value it happens to land on ("...:05Z", "...:05.5Z", "...:05.000000001Z"). Fixed width
+// keeps every event the same shape, which is what makes a byte-wise comparison of two
+// UTC event timestamps agree with their chronological order -- something SIEM queries,
+// `sort` over a JSONL tail, and human eyes on a log all end up relying on.
+const TimestampFormat = "2006-01-02T15:04:05.000000000Z07:00"
+
+// FormatTimestamp renders t as a canonical Beacon event timestamp. Every writer of the
+// endpoint event stream goes through here, so the two capture paths -- the hook adapter
+// and the collector exporter -- stamp the same instant the same way.
+func FormatTimestamp(t time.Time) string {
+ return t.UTC().Format(TimestampFormat)
+}
+
+// ParseTimestamp parses a Beacon event timestamp. It accepts the canonical nanosecond
+// form and the second-resolution RFC3339 that agents wrote before nanosecond stamping,
+// so a log spanning an agent upgrade still reads back end to end.
+func ParseTimestamp(value string) (time.Time, error) {
+ return time.Parse(time.RFC3339Nano, value)
+}
+
+// Sequencer hands out the monotonic emission counter carried in Event.Sequence. It is
+// safe for concurrent use, which the hook adapter needs (a single hook invocation can
+// emit several events) and the collector exporter needs (the pipeline may call the
+// consume functions for logs, traces and metrics at the same time).
+type Sequencer struct {
+ n atomic.Uint64
+}
+
+// Next returns the next sequence number for this writer, starting at 1. Zero is reserved
+// to mean "unsequenced" so an absent counter is distinguishable from the first event, and
+// is never handed out.
+func (s *Sequencer) Next() uint64 {
+ return s.n.Add(1)
+}
diff --git a/pkg/asymptoteobserve/ordering_test.go b/pkg/asymptoteobserve/ordering_test.go
new file mode 100644
index 00000000..8c449db4
--- /dev/null
+++ b/pkg/asymptoteobserve/ordering_test.go
@@ -0,0 +1,145 @@
+package asymptoteobserve
+
+import (
+ "sync"
+ "testing"
+ "time"
+)
+
+func TestFormatTimestampKeepsSubSecondPrecision(t *testing.T) {
+ // The finding that motivated this: 0 of 5,595 events in a real runtime log carried a
+ // sub-second timestamp, so 97% of them shared a timestamp with another event in the
+ // same session and nothing could order them.
+ at := time.Date(2026, 8, 21, 9, 14, 3, 123456789, time.UTC)
+ if got, want := FormatTimestamp(at), "2026-08-21T09:14:03.123456789Z"; got != want {
+ t.Fatalf("FormatTimestamp = %q, want %q", got, want)
+ }
+}
+
+func TestFormatTimestampIsFixedWidth(t *testing.T) {
+ // time.RFC3339Nano would render these at three different widths, because it trims
+ // trailing zeros from the fractional second.
+ cases := []time.Time{
+ time.Date(2026, 8, 21, 9, 14, 3, 0, time.UTC),
+ time.Date(2026, 8, 21, 9, 14, 3, 500000000, time.UTC),
+ time.Date(2026, 8, 21, 9, 14, 3, 1, time.UTC),
+ }
+ want := len(FormatTimestamp(cases[0]))
+ for _, at := range cases {
+ if got := FormatTimestamp(at); len(got) != want {
+ t.Fatalf("FormatTimestamp(%s) = %q (%d chars), want %d chars", at, got, len(got), want)
+ }
+ }
+ if got, want := FormatTimestamp(cases[0]), "2026-08-21T09:14:03.000000000Z"; got != want {
+ t.Fatalf("whole second = %q, want %q (zeros retained)", got, want)
+ }
+}
+
+func TestFormatTimestampSortsByteWiseInChronologicalOrder(t *testing.T) {
+ // Fixed width is what lets a SIEM query, a `sort` over a JSONL tail, or the
+ // dashboard summary compare two timestamps as strings and get the right answer.
+ base := time.Date(2026, 8, 21, 9, 14, 3, 0, time.UTC)
+ prev := ""
+ for _, offset := range []time.Duration{
+ 0, time.Nanosecond, time.Microsecond, 500 * time.Millisecond,
+ time.Second, 61 * time.Second,
+ } {
+ got := FormatTimestamp(base.Add(offset))
+ if prev != "" && !(prev < got) {
+ t.Fatalf("string order disagrees with time order: %q not before %q", prev, got)
+ }
+ prev = got
+ }
+}
+
+func TestFormatTimestampNormalizesToUTC(t *testing.T) {
+ zone := time.FixedZone("UTC-7", -7*60*60)
+ at := time.Date(2026, 8, 21, 2, 14, 3, 0, zone)
+ if got, want := FormatTimestamp(at), "2026-08-21T09:14:03.000000000Z"; got != want {
+ t.Fatalf("FormatTimestamp = %q, want %q", got, want)
+ }
+}
+
+func TestParseTimestampRoundTrips(t *testing.T) {
+ at := time.Date(2026, 8, 21, 9, 14, 3, 123456789, time.UTC)
+ got, err := ParseTimestamp(FormatTimestamp(at))
+ if err != nil {
+ t.Fatalf("ParseTimestamp returned error: %v", err)
+ }
+ if !got.Equal(at) {
+ t.Fatalf("round trip = %s, want %s", got, at)
+ }
+}
+
+func TestParseTimestampReadsLegacySecondResolution(t *testing.T) {
+ // A log written before nanosecond stamping has to keep reading back: an installed
+ // agent upgrades mid-log, and the active runtime.jsonl spans both.
+ got, err := ParseTimestamp("2026-08-21T09:14:03Z")
+ if err != nil {
+ t.Fatalf("ParseTimestamp returned error: %v", err)
+ }
+ if want := time.Date(2026, 8, 21, 9, 14, 3, 0, time.UTC); !got.Equal(want) {
+ t.Fatalf("parsed = %s, want %s", got, want)
+ }
+}
+
+func TestParseTimestampRejectsNonTimestamps(t *testing.T) {
+ for _, value := range []string{"", "not-a-time", "1755767643"} {
+ if _, err := ParseTimestamp(value); err == nil {
+ t.Fatalf("ParseTimestamp(%q) succeeded, want error", value)
+ }
+ }
+}
+
+func TestNewEventStampsSubSecondPrecision(t *testing.T) {
+ event := NewEvent(NewEventOptions{Action: "session.started", Harness: HarnessInfo{Name: "claude_code"}})
+ if len(event.Timestamp) != len(FormatTimestamp(time.Now())) {
+ t.Fatalf("event timestamp = %q, want canonical fixed-width form", event.Timestamp)
+ }
+ if _, err := ParseTimestamp(event.Timestamp); err != nil {
+ t.Fatalf("event timestamp %q does not parse: %v", event.Timestamp, err)
+ }
+}
+
+func TestSequencerStartsAtOneAndAdvances(t *testing.T) {
+ var s Sequencer
+ // Zero is the schema's "unsequenced", so it must never be handed out.
+ for want := uint64(1); want <= 3; want++ {
+ if got := s.Next(); got != want {
+ t.Fatalf("Next() = %d, want %d", got, want)
+ }
+ }
+}
+
+func TestSequencerIsConcurrencySafe(t *testing.T) {
+ // The exporter's log, trace and metric consumers can run at the same time, and one
+ // hook invocation emits several events; a duplicated number would silently
+ // mis-order them.
+ var (
+ s Sequencer
+ wg sync.WaitGroup
+ mu sync.Mutex
+ seen = map[uint64]bool{}
+ )
+ for i := 0; i < 32; i++ {
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ for j := 0; j < 32; j++ {
+ n := s.Next()
+ mu.Lock()
+ if seen[n] {
+ mu.Unlock()
+ t.Errorf("sequence %d handed out twice", n)
+ return
+ }
+ seen[n] = true
+ mu.Unlock()
+ }
+ }()
+ }
+ wg.Wait()
+ if len(seen) != 32*32 {
+ t.Fatalf("handed out %d distinct sequences, want %d", len(seen), 32*32)
+ }
+}
diff --git a/pkg/asymptoteobserve/threatrules/correlation.go b/pkg/asymptoteobserve/threatrules/correlation.go
index 46b67c31..648e3179 100644
--- a/pkg/asymptoteobserve/threatrules/correlation.go
+++ b/pkg/asymptoteobserve/threatrules/correlation.go
@@ -27,9 +27,10 @@ func (c *CompiledRule) evaluateCorrelation(events []asymptoteobserve.Event) (Ver
// alignment in one session that satisfies the sequence within the window, or nil if none.
//
// Steps must occur in order; the elapsed time from the first matched step to the final
-// matched step must not exceed the window. Timestamps are RFC3339; if a step's timestamp
-// is absent the window is not enforced against it (positive fixtures need not carry
-// timestamps, while window fixtures supply them).
+// matched step must not exceed the window. "In order" means the order of the slice, which
+// the caller is responsible for (see SortEvents); if a step's timestamp is absent the
+// window is not enforced against it (positive fixtures need not carry timestamps, while
+// window fixtures supply them).
func (c *CompiledRule) matchSession(events []asymptoteobserve.Event) ([]asymptoteobserve.Event, error) {
// Try every step-0 match as a candidate anchor. A single greedy pass is not enough:
// an early anchor whose final step falls outside the window must not mask a later
@@ -107,13 +108,13 @@ func groupBySession(events []asymptoteobserve.Event) (map[string][]asymptoteobse
return groups, order
}
-// eventTime parses an event's RFC3339 timestamp. The bool is false when the timestamp is
-// absent or unparseable, in which case window enforcement is skipped for that event.
+// eventTime parses an event's timestamp. The bool is false when the timestamp is absent
+// or unparseable, in which case window enforcement is skipped for that event.
func eventTime(e asymptoteobserve.Event) (time.Time, bool) {
if e.Timestamp == "" {
return time.Time{}, false
}
- t, err := time.Parse(time.RFC3339, e.Timestamp)
+ t, err := asymptoteobserve.ParseTimestamp(e.Timestamp)
if err != nil {
return time.Time{}, false
}
diff --git a/pkg/asymptoteobserve/threatrules/ordering.go b/pkg/asymptoteobserve/threatrules/ordering.go
new file mode 100644
index 00000000..c05c1975
--- /dev/null
+++ b/pkg/asymptoteobserve/threatrules/ordering.go
@@ -0,0 +1,65 @@
+package threatrules
+
+import (
+ "sort"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// SortEvents puts a raw event stream into the order the events actually happened, in
+// place, so correlation stops inheriting the order the lines happened to land in the log.
+//
+// Append order is not emission order. The hook adapter writes synchronously the moment a
+// tool call is intercepted, while the collector exporter writes on its export interval,
+// so a hook event for 10:00:01 routinely lands in the file after a collector event for
+// 10:00:06. The rules engine evaluates an ordered sequence by contract (see
+// spec/threat-rules/SPEC.md), which makes putting the stream in order the caller's job:
+// every ordered-window rule silently misses when it is handed append order instead.
+//
+// The key is (timestamp, sequence, input position):
+//
+// - Timestamp first, because it is the only field both writers stamp from the same
+// clock and is therefore the one thing comparable across capture paths.
+// - Sequence second, but only when both events carry one, since it orders a single
+// writer's stream rather than the log as a whole (see asymptoteobserve.Event.Sequence).
+// It is what separates a batch of metric datapoints that all carry one export's
+// collection instant.
+// - Input position last, so the result is a total order and one log always sorts one
+// way, rather than depending on the sort implementation.
+//
+// An event whose timestamp is absent or unparseable inherits the last timestamp seen
+// before it. That keeps it beside the events it arrived with instead of collapsing every
+// such event to the epoch and dragging it to the front of the session.
+func SortEvents(events []asymptoteobserve.Event) {
+ if len(events) < 2 {
+ return
+ }
+ type keyed struct {
+ event asymptoteobserve.Event
+ at time.Time
+ seq uint64
+ idx int
+ }
+ keys := make([]keyed, len(events))
+ var carried time.Time
+ for i := range events {
+ if at, ok := eventTime(events[i]); ok {
+ carried = at
+ }
+ keys[i] = keyed{event: events[i], at: carried, seq: events[i].Sequence, idx: i}
+ }
+ sort.Slice(keys, func(i, j int) bool {
+ a, b := keys[i], keys[j]
+ if !a.at.Equal(b.at) {
+ return a.at.Before(b.at)
+ }
+ if a.seq != 0 && b.seq != 0 && a.seq != b.seq {
+ return a.seq < b.seq
+ }
+ return a.idx < b.idx
+ })
+ for i := range keys {
+ events[i] = keys[i].event
+ }
+}
diff --git a/pkg/asymptoteobserve/threatrules/ordering_test.go b/pkg/asymptoteobserve/threatrules/ordering_test.go
new file mode 100644
index 00000000..fa3dc996
--- /dev/null
+++ b/pkg/asymptoteobserve/threatrules/ordering_test.go
@@ -0,0 +1,205 @@
+package threatrules
+
+import (
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// actions renders a sorted stream compactly so a failure shows the order it produced.
+func actions(events []asymptoteobserve.Event) []string {
+ out := make([]string, 0, len(events))
+ for _, e := range events {
+ out = append(out, e.Event.Action)
+ }
+ return out
+}
+
+func equalStrings(a, b []string) bool {
+ if len(a) != len(b) {
+ return false
+ }
+ for i := range a {
+ if a[i] != b[i] {
+ return false
+ }
+ }
+ return true
+}
+
+func TestSortEventsPutsAppendOrderIntoEmissionOrder(t *testing.T) {
+ // The append order a real runtime log lands in: the collector exporter flushes on its
+ // export interval, so its 10:00:06 event is written before the hook's synchronous
+ // 10:00:01 event even though the hook's event happened first.
+ events := []asymptoteobserve.Event{
+ corrEvent("2026-08-21T10:00:06.000000000Z", "session.activity", "s1", nil),
+ corrEvent("2026-08-21T10:00:01.000000000Z", "file.read", "s1", withEnv),
+ corrEvent("2026-08-21T10:00:03.000000000Z", "command.executed", "s1", withCurl),
+ }
+ SortEvents(events)
+ want := []string{"file.read", "command.executed", "session.activity"}
+ if got := actions(events); !equalStrings(got, want) {
+ t.Fatalf("order = %v, want %v", got, want)
+ }
+}
+
+func TestSortEventsMakesOrderedCorrelationFireOnAppendOrder(t *testing.T) {
+ // The failure this workstream is about: read-then-egress happened in order, but the
+ // egress event reached the log first, so the ordered-window rule saw the reverse and
+ // silently missed.
+ c := readThenEgressRule(t)
+ appended := []asymptoteobserve.Event{
+ corrEvent("2026-08-21T10:00:30.000000000Z", "command.executed", "s1", withCurl),
+ corrEvent("2026-08-21T10:00:00.000000000Z", "file.read", "s1", withEnv),
+ }
+
+ verdict, err := c.Evaluate(appended)
+ if err != nil {
+ t.Fatalf("eval: %v", err)
+ }
+ if verdict != VerdictNoMatch {
+ t.Fatalf("append order should miss (that is the bug), got %s", verdict)
+ }
+
+ SortEvents(appended)
+ verdict, err = c.Evaluate(appended)
+ if err != nil {
+ t.Fatalf("eval: %v", err)
+ }
+ if verdict != VerdictMatch {
+ t.Fatalf("sorted stream want match, got %s", verdict)
+ }
+}
+
+func TestSortEventsBreaksTimestampTiesOnSequence(t *testing.T) {
+ // One metric export flushes datapoints that all carry that export's collection
+ // instant, so they tie however precise the timestamp is. Sequence is the only thing
+ // left that knows which came first.
+ tie := "2026-08-21T10:00:00.000000000Z"
+ events := []asymptoteobserve.Event{
+ corrEvent(tie, "third", "s1", func(e *asymptoteobserve.Event) { e.Sequence = 30 }),
+ corrEvent(tie, "first", "s1", func(e *asymptoteobserve.Event) { e.Sequence = 10 }),
+ corrEvent(tie, "second", "s1", func(e *asymptoteobserve.Event) { e.Sequence = 20 }),
+ }
+ SortEvents(events)
+ want := []string{"first", "second", "third"}
+ if got := actions(events); !equalStrings(got, want) {
+ t.Fatalf("order = %v, want %v", got, want)
+ }
+}
+
+func TestSortEventsKeepsTimestampAheadOfSequence(t *testing.T) {
+ // Sequence orders one writer's stream, not the log: the hook process that emitted
+ // sequence 1 may have started long after the exporter reached sequence 900. The
+ // timestamp is the only cross-writer key, so it has to win.
+ events := []asymptoteobserve.Event{
+ corrEvent("2026-08-21T10:00:05.000000000Z", "hook", "s1", func(e *asymptoteobserve.Event) { e.Sequence = 1 }),
+ corrEvent("2026-08-21T10:00:01.000000000Z", "exporter", "s1", func(e *asymptoteobserve.Event) { e.Sequence = 900 }),
+ }
+ SortEvents(events)
+ if got := actions(events); !equalStrings(got, []string{"exporter", "hook"}) {
+ t.Fatalf("order = %v, want exporter before hook", got)
+ }
+}
+
+func TestSortEventsIgnoresUnsequencedTie(t *testing.T) {
+ // A zero sequence means "unsequenced", not "first". Events written before sequence
+ // stamping must keep the order they arrived in rather than being dragged ahead of
+ // everything that does carry a counter.
+ tie := "2026-08-21T10:00:00.000000000Z"
+ events := []asymptoteobserve.Event{
+ corrEvent(tie, "legacy", "s1", nil),
+ corrEvent(tie, "sequenced", "s1", func(e *asymptoteobserve.Event) { e.Sequence = 7 }),
+ }
+ SortEvents(events)
+ if got := actions(events); !equalStrings(got, []string{"legacy", "sequenced"}) {
+ t.Fatalf("order = %v, want input order preserved", got)
+ }
+}
+
+func TestSortEventsKeepsUnstampedEventsBesideTheirNeighbours(t *testing.T) {
+ // An event with no parseable timestamp inherits the last one seen, so it stays where
+ // it arrived instead of collapsing to the epoch and jumping to the front.
+ events := []asymptoteobserve.Event{
+ corrEvent("2026-08-21T10:00:05.000000000Z", "late", "s1", nil),
+ corrEvent("2026-08-21T10:00:01.000000000Z", "early", "s1", nil),
+ corrEvent("", "early-companion", "s1", nil),
+ corrEvent("not-a-timestamp", "early-companion-2", "s1", nil),
+ }
+ SortEvents(events)
+ want := []string{"early", "early-companion", "early-companion-2", "late"}
+ if got := actions(events); !equalStrings(got, want) {
+ t.Fatalf("order = %v, want %v", got, want)
+ }
+}
+
+func TestSortEventsLeavesAnUnstampedStreamAlone(t *testing.T) {
+ // Conformance fixtures carry no timestamps at all; their given order is the sequence
+ // under test and must survive.
+ events := []asymptoteobserve.Event{
+ corrEvent("", "one", "s1", nil),
+ corrEvent("", "two", "s1", nil),
+ corrEvent("", "three", "s1", nil),
+ }
+ SortEvents(events)
+ if got := actions(events); !equalStrings(got, []string{"one", "two", "three"}) {
+ t.Fatalf("order = %v, want input order preserved", got)
+ }
+}
+
+func TestSortEventsIsATotalOrder(t *testing.T) {
+ // Same log in, same order out -- including for events that tie on every key, which
+ // fall back to input position rather than to whatever the sort implementation does.
+ tie := "2026-08-21T10:00:00.000000000Z"
+ build := func() []asymptoteobserve.Event {
+ return []asymptoteobserve.Event{
+ corrEvent(tie, "a", "s1", nil),
+ corrEvent(tie, "b", "s2", nil),
+ corrEvent(tie, "c", "s1", nil),
+ corrEvent("2026-08-21T09:59:59.999999999Z", "d", "s1", nil),
+ }
+ }
+ first := build()
+ SortEvents(first)
+ for i := 0; i < 5; i++ {
+ again := build()
+ SortEvents(again)
+ if !equalStrings(actions(first), actions(again)) {
+ t.Fatalf("run %d = %v, want %v", i, actions(again), actions(first))
+ }
+ }
+ if got := actions(first); !equalStrings(got, []string{"d", "a", "b", "c"}) {
+ t.Fatalf("order = %v, want [d a b c]", got)
+ }
+}
+
+func TestSortEventsHandlesShortStreams(t *testing.T) {
+ SortEvents(nil)
+ one := []asymptoteobserve.Event{corrEvent("2026-08-21T10:00:00.000000000Z", "only", "s1", nil)}
+ SortEvents(one)
+ if got := actions(one); !equalStrings(got, []string{"only"}) {
+ t.Fatalf("order = %v, want [only]", got)
+ }
+}
+
+func TestSortEventsOrdersAcrossSessions(t *testing.T) {
+ // Correlation groups by session after the sort, so interleaved sessions have to come
+ // out of the sort correctly ordered within each one.
+ events := []asymptoteobserve.Event{
+ corrEvent("2026-08-21T10:00:04.000000000Z", "s2-second", "s2", nil),
+ corrEvent("2026-08-21T10:00:03.000000000Z", "s1-second", "s1", nil),
+ corrEvent("2026-08-21T10:00:02.000000000Z", "s2-first", "s2", nil),
+ corrEvent("2026-08-21T10:00:01.000000000Z", "s1-first", "s1", nil),
+ }
+ SortEvents(events)
+ groups, order := groupBySession(events)
+ if !equalStrings(order, []string{"s1", "s2"}) {
+ t.Fatalf("session order = %v, want [s1 s2]", order)
+ }
+ if got := actions(groups["s1"]); !equalStrings(got, []string{"s1-first", "s1-second"}) {
+ t.Fatalf("s1 = %v", got)
+ }
+ if got := actions(groups["s2"]); !equalStrings(got, []string{"s2-first", "s2-second"}) {
+ t.Fatalf("s2 = %v", got)
+ }
+}
diff --git a/spec/threat-rules/FIELDS.md b/spec/threat-rules/FIELDS.md
index a424dd7e..3ceecc40 100644
--- a/spec/threat-rules/FIELDS.md
+++ b/spec/threat-rules/FIELDS.md
@@ -125,6 +125,7 @@ Regenerate with `beacon rules fields --markdown > spec/threat-rules/FIELDS.md`.
| `e.run.run_id` | string |
| `e.run.workflow` | string |
| `e.schema_version` | string |
+| `e.sequence` | uint |
| `e.server.address` | string |
| `e.server.port` | int |
| `e.session.id` | string |
diff --git a/spec/threat-rules/SPEC.md b/spec/threat-rules/SPEC.md
index f3a1b89c..e15b6b33 100644
--- a/spec/threat-rules/SPEC.md
+++ b/spec/threat-rules/SPEC.md
@@ -124,6 +124,12 @@ Exactly one of `match` or `correlation` must be present. Required:
## Verdict model
+An engine evaluates the sequence it is given; putting a real event stream into the order the
+events happened is the caller's responsibility. Beacon events carry a nanosecond `timestamp`
+and an optional per-writer `sequence` for that purpose, and `beacon scan` sorts by
+`(timestamp, sequence)` before evaluating — the order lines appear in a log is not their
+emission order.
+
An engine produces one of two verdicts for a rule against an ordered event sequence:
- `match` — the rule fired.