Ambient state snapshots, build-attributed sessions, and span tooling that can't lie

[kyleve]

Three related things, all in service of being able to read a log weeks later and know what it meant: the system state behind every event, the build behind every session, and span surfaces that don't render claims their data can't support.

Closes nine backlog entries — the ambient-snapshot P0 in Shared/Periscope/TODOs.md, the LogSession build-naming P2 in the root TODOs.md, and seven span-tooling / docs quick wins.

Ambient state snapshots

Every event already referenced one SDLogSession row for "which build, on which device". It now also references one SDAmbientSnapshot row for "what was the system doing" — network, thermal state, power mode, lifecycle — so correlating an error with connectivity stops being a timestamp hunt.

• AmbientEvent.reporting (.state / .occurrence) draws the line between a lasting condition and a passing moment. A memory warning is the one built-in .occurrence: the app is not "in a memory warning" afterwards, so it must not stick to every later record.
• AmbientSnapshot is the latest value of every stateful kind, and its identity is the dedupe key — applying(_:) returns self whenever nothing actually moved, so a run of records sharing one state shares one stored row. folding(_:into:) makes an empty snapshot unrepresentable: a row describing the system while carrying no values would be worse than an honest nil.
• The pipeline folds and stamps in the existing in-lock buffer path, which now returns the record as buffered so the journal and the sinks get the stamped copy. Folding happens before stamping, so an ambient event carries the state it announces rather than the one it replaced.
• The crash journal carries it, so records that only exist because of a crash still say what the system was doing.
• Storage is one row per distinct state plus an indexed ambientSnapshotID, and retention takes unreferenced snapshots with it.
• Thermal state and low-power mode report at started(), so their state isn't unknown until it next changes.

A session can name the build it came from

LogSession.current() read only CFBundleShortVersionString / CFBundleVersion, and the Where app pins both in the manifest — so every developer build read v1.0 (1) and weeks-old logs couldn't be tied to the code that produced them.

LogSession.attributes ([LogSessionAttributeKey: String]) is the seam: the host app fills it at bootstrap, keeping Periscope below the Where modules rather than reaching up for a build stamp. Where's stamp-build-info.sh now writes WhereConfiguration / WhereSwiftOptimizationLevel / WhereSwiftCompilationMode beside the commit keys, BuildInfo reads them back, and the viewer's session picker shows commit + optimization level.

The optimization level is the load-bearing field, not the commit: a span duration from an -Onone build says nothing about the shipping app, and the configuration alone can't answer it (a Debug configuration can be compiled -O). So SpanHistoryView also gained a build scope — all builds, this session, or every session built at the current one's level — and labels the active scope, because a p95 that silently pools an unoptimized build with an optimized one measures nothing.

Span tooling that can't lie

• SpanNode carried parallel ended / exitMode / duration optionals, so a span whose end payload failed to decode rendered an exit chip beside a "running" duration — a reading that cannot be true, since the exit comes from an indexed column and the duration from the payload. One Outcome replaces them, and its Timing distinguishes an end that measured nothing (an orphan) from one whose payload wouldn't decode.
• Span history labels a recovered bucket as recovered. A SpanEnded whose payload won't decode still groups (by its message), but the row says the name isn't the recorded one instead of minting what looks like a real span kind.
• Every read model logs its failures to PeriscopeToolsLog.failures — deliberately OSLog, not Periscope: these surfaces reload on every store commit, so logging into the store they read would turn one corrupt row into a refresh loop.
• The orphan sweep stops parsing payloads to decide relaunches. SpanRelaunchPolicy persists as a column on the began row. A row predating the column falls back to its payload, and a payload that can't be read can't prove the span asked to survive — so it's closed, with the failure logged rather than silently deciding against the policy.
• SpanTreeRow reads \.logRowDensity instead of hard-coding comfortable, so the viewer's density picker actually reaches span-tree rows.

Notable decisions

• Two ambient stamping sites, not one. The drop report is synthesized during the drain and never passes through the buffer path, so it is stamped where it is constructed — otherwise the one record that marks a gap in the history couldn't say what the system was doing when the gap opened.
• No app-lifecycle startup baseline. Emitting one means reading UIApplication.shared.applicationState at launch, which reads .background even for a user tap under the UIScene lifecycle — the trap LifecycleReason.undetermined exists to avoid. A baseline there would stamp a confidently wrong value on every early record; the first real transition fills it correctly a moment later. A test pins the omission so it reads as deliberate.
• An unstamped bundle claims nothing. BuildInfo.logSessionAttributes is empty rather than reporting the stamp script's unknown placeholder as a configuration — a session that can't name its build should read as unidentified, not as a build called "unknown".
• Decode tolerance where builds meet. AmbientEvent goes to v2 and LogSession gains a hand-written init(from:), because synthesized decoding throws on a missing key and older rows/journals don't have the new fields. Both have a test that feeds the decoder the old shape.
• Migration is verified, not assumed. The new columns are optional so SwiftData can infer a lightweight migration. A store written by the pre-change schema (from a git worktree at that commit) was opened under the new one: old rows read back with ambient state honestly absent, and later writes committed with zero write failures.
• degradeSpanBegan is a test seam for degraded on-disk shapes. Nothing a test can write produces a payload that won't decode or a missing policy column, so the sweep's fallback branch was unreachable from a test without it.

Testing

tuist test Stuff-iOS-Tests passes in full (the multi-bundle scheme, not just the isolated bundles). New coverage spans the snapshot value type, pipeline stamping (including spans, the drop report, and live observers), journal round-trip and crash recovery, store dedupe / reads / orphan pruning, session attribute round-tripping, the build-scope filter, the span outcome model under unreadable payloads, and the relaunch column plus its payload fallback.

  

[kyleve]

Wait, what?

[kyleve]

This seems weird!