wehub-resource-sync
40 lines
2.2 KiB
Markdown
40 lines
2.2 KiB
Markdown
# AdaptiveReplayKit
|
|
|
|
`AdaptiveReplayKit` is an offline harness for comparing refresh-timing policies against an
|
|
explicit JSONL trace. `AdaptiveReplayCLI` is the command-line wrapper around the library.
|
|
|
|
## Scope
|
|
|
|
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.
|
|
|
|
## Components
|
|
|
|
- `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.
|