The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
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.goindex 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 IDssc := 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 windowsc := 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.goindex 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.goindex 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.gonew file mode 100644index 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.goindex 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.goindex 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 * 1024defaultEndpointRotateArchives = 5@@ -126,7 +130,14 @@ func (l *Logger) baseEndpointEvent(action, category, severity, message string) muser["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.goindex 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.gonew file mode 100644index 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.goindex 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, []strincontinue}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.goindex 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.goindex 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.goindex 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) (Finreturn 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.goindex 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 *EventRescontinue}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.gonew file mode 100644index 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.goindex 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.Timefor _, 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.jsonindex 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.jsonindex 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.goindex 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.Severityconst (diff --git a/cli/beacon/internal/tokens/tokens.go b/cli/beacon/internal/tokens/tokens.goindex 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.goindex 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 jsonlWriterlogger *zap.Loggerconverter 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_ = ctxvar firstErr errorfor _, 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_ = ctxvar firstErr errorfor _, 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_ = ctxvar firstErr errorfor _, 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.Metreturn 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.goindex 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.goindex 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.goindex 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.GenAIUsageReasoningInfotype GenAIWorkflowInfo = asymptoteobserve.GenAIWorkflowInfotype 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.gonew file mode 100644index 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.mdxindex 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).+## FindingsWhen a rule fires, Beacon emits a finding. Findings include:diff --git a/docs/log-forwarding/falcon.mdx b/docs/log-forwarding/falcon.mdxindex 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.productdiff --git a/docs/telemetry-schema/event-schema.mdx b/docs/telemetry-schema/event-schema.mdxindex 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 OpenTelemetryBeacon 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.mdxindex 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.mdxindex 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.goindex 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.goindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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][]asymptoteobsereturn 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.gonew file mode 100644index 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.gonew file mode 100644index 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.mdindex 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.mdindex 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.