Sources/AdaptiveReplayKit/README.md
AdaptiveReplayKit is an offline harness for comparing refresh-timing policies against an
explicit JSONL trace. AdaptiveReplayCLI is the command-line wrapper around the library.
The replay targets do not import CodexBar or CodexBarCore; they share only the package-internal,
Foundation-only AdaptiveRefreshCore target with the app. They do not record app behavior, scan
Codex or Claude transcript directories, write trace files, call providers, or change the production
refresh policy. Trace capture and lifecycle management are deliberately outside this PR; callers
provide an existing trace path to the CLI.
Optional activity fields in the trace schema are inputs only. The replay kit never discovers or collects them. Old records without those fields continue to decode.
AdaptiveRefreshTrace.swift defines the version-tolerant trace schema.AdaptiveRefreshTraceParser.swift parses JSONL strictly by default. The tolerant entry point is
available for exploratory work that explicitly accepts skipped malformed records.AdaptiveRefreshCore owns the production decision table. ReplayPolicy.swift,
BaselinePolicies.swift, and CandidatePolicies.swift provide replay adapters, fixed/manual
baselines, and the replay-only activity candidate.ReplayEngine.swift and ReplayMetrics.swift calculate simulated refresh cadence, menu-open
staleness, interaction advances, and constrained-state compliance.ReplayTraceSegmentation.swift excludes legacy deadline-overrun gaps with an explicit heuristic
and reports the excluded duration.RecordedScheduleAudit.swift audits recorded timer-advance events independently from the replay
clock.Sources/AdaptiveReplayCLI formats table or JSON reports.interactionAdvanceCount is counterfactual. Replay assumes a zero-duration refresh, while the
live app waits for provider work and may already have a refresh in flight. Recorded schedule events
therefore have a separate audit instead of a direct count comparison.
The legacy gap heuristic cannot distinguish sleep or reboot from a long refresh or event-loop stall. Reports expose the segment count, grace interval, and excluded time rather than assigning a cause.