Skip to content

spec(AST-137): React Native platform: Diagnostics (draft) - #12570

Closed
imdreamrunner wants to merge 6 commits into
mainfrom
spec/ast-137-react-native-diagnostics
Closed

imdreamrunner wants to merge 6 commits into
mainfrom
spec/ast-137-react-native-diagnostics

Conversation

@imdreamrunner

@imdreamrunner imdreamrunner commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Depends on #12563 (spec:AST-112 as amended), #12594 (spec:AST-140, platform code rules), and #12553 (spec:AST-130). The record cites spec:AST-112 FR1, FR4, FR5, FR7, FR15 and DEC-16, spec:AST-140 FR1, FR3, FR5 and FR6, and spec:AST-130 FR8 and FR18. Merge order: #12576 → #12563 → the platform group records, this one included.

Exact decision needed

The target contract of the React Native platform's diagnostics modules, as the record spec:AST-137 (docs/specs/AST-137-react-native-diagnostics/spec.md) states them: AstryxCrashReports (the app's own crash reports, kept on the device), AstryxDailyMetrics (the system's last day of measures of the app), and the test-only AstryxFrameRecorder (what the screen shows at every frame, for behaviour checks). It covers each module's methods, results and reasons, the crash reporters' opt-in and how they coexist with other reporters, the test-build crash trigger, the daily record, the per-frame samples and recordFrames, privacy (nothing leaves the device), threads, the revision-1 baseline with named features, and where each piece belongs: crash reports and daily metrics in the optional add-on package, not the core package; the frame recorder test-only. Astryx Stage (spec:AST-139) and Preview in the Astryx app (spec:AST-141) are separate products that conform to these contracts. The platform info and launch timing belong to spec:AST-130 and are referenced, not restated.

Existing authority searched

  • spec:AST-112 (React Native foundation): FR1 (the package's modules), FR3 (opt-in capabilities), FR4 (app-level native settings through the configuration plugin), FR5 (./testing), FR7 (capability shape), FR15 (evidence), DEC-16 (native code an app would get from a library ships with Astryx). FR1 does not list diagnostics; this record places them in the optional add-on package.
  • spec:AST-140 (React Native platform code, open as a draft): FR1 (registration), FR3 (result vocabulary), FR5 (additive evolution), FR6 (threads). This record follows them.
  • spec:AST-130 (System modules, open as a draft): FR8 (AstryxPlatformInfo: the feature rows, the run's launch and memory) and FR18 (named features through contractFeatures). Referenced; unchanged.
  • spec:AST-139 (Astryx Stage) and spec:AST-141 (Preview in the Astryx app): separate products that own how Stage and Preview run these modules; this record states no Stage or Preview behaviour.
  • docs/specs/ searched for AstryxCrashReports, AstryxDailyMetrics, AstryxFrameRecorder, recordFrames, crash, MetricKit, frame recorder: no record owns these contracts.
  • Open pull requests searched for AST-137, crash, metrics, diagnostics, and React Native platform: only the sibling platform group drafts; AST-130 names this group as out of its scope. AST-137 is free on main, in open pull request titles, and in remote branches.

Decision

The record's requirements FR1 to FR10, FR12, and FR13, and DEC-1 to DEC-4:

  • Three native modules: crash reports and daily metrics in the optional add-on package, not the core package; the frame recorder a Debug-only test module reached through ./testing.
  • No third-party native dependency; apps may use third-party libraries beside these components without conflict.
  • Results never throw; closed reasons per module (not-declared; os and unavailable; unavailable, busy, not-recording). recordFrames is the one throwing call: a test step that cannot record fails, never passes with nothing checked.
  • Crash reports are off until the app opts in through the configuration plugin; when on they install before the first frame and keep MetricKit diagnostics, uncaught exceptions, and fatal signals, whole and for 14 days.
  • The crash reporters chain to and hand on to every other reporter, so the system's report and other reporters keep the original exception.
  • crashForTest crashes only a test build that declares the trigger; release checks refuse a shipped build that does.
  • A recording that stops itself after 60 seconds answers ok with its samples and isTimedOut: true.
  • Daily metrics keep the newest system payload only: scroll hitches, peak memory, and median time to first frame; Android answers os.
  • Nothing leaves the device unless the app sends it; the app scrubs and attributes what it sends.
  • Every contract at revision 1 with no revision counter; later behaviour is a named feature.
  • Public platform API only, no exception.

Who uses it

Native piece Kind Astryx components that use it What a person sees
AstryxCrashReports native module (Turbo Native Module) No Astryx component; app API only (the add-on package's main entry: AstryxCrashReports) Nothing by itself. On the launch after a crash, an app can show its own notice or offer to send a report the person allows.
AstryxDailyMetrics native module (Turbo Native Module) No Astryx component; app API only (the add-on package's main entry: AstryxDailyMetrics) Nothing by itself. An app's diagnostics screen can show the last day's scroll hitches, peak memory, and launch time.
AstryxFrameRecorder native module (Turbo Native Module), test-only (Debug) No Astryx component; test API only: the library's behaviour contract cases through ./testing's recordFrames Nothing: a person never meets it. A failed check names the frame where a bar or a view moved out of place.

Rejected alternatives

  • Leaving crashes and daily measures to a third-party SDK: the app then carries native code of its own (DEC-1).
  • A JavaScript call that turns crash reporting on: it runs too late to see a crash at launch (DEC-2).
  • A built-in upload: the platform would pick a destination and collect data on every app's behalf (DEC-3).
  • The frame recorder in Release binaries: every shipped app would carry a per-frame reader of its view tree (DEC-4).

Claim scope and non-goals

The record governs AstryxCrashReports, AstryxDailyMetrics, AstryxFrameRecorder, and ./testing's recordFrames and isFrameRecorderAvailable. It leaves out what AstryxPlatformInfo reports (spec:AST-130/FR8), JavaScript error reporting, symbolication and upload, hang and other termination diagnostics, Android exit reasons (OQ1), and frame-rate measurement. Astryx Stage (spec:AST-139) and Preview in the Astryx app (spec:AST-141) are separate products.

Evidence and implementation relationship

The implementation lives in the optional add-on package's platform layer (crash reports, daily metrics) and the core package's ./testing entry (the frame recorder). No public evidence links. "Why this exists" keeps one conclusion per module: whether an app's alternative needs native code, and the gap. Two gaps are recorded: the opt-in refusal answers unsupported instead of not-declared (FR2), and a self-stopped recording answers timed-out instead of ok with isTimedOut (FR7).

Survey behind "Why this exists"

The record keeps one conclusion per module; the comparison it rests on:

Module What the ecosystem does well Whether the alternative needs native code, and the gap
AstryxCrashReports @sentry/react-native, Firebase Crashlytics, and Bugsnag catch native crashes and JavaScript errors, symbolicate, group, and upload them to a service; react-native-exception-handler catches native exceptions on the device. Each ships native code and sends to its own service. Gap: on-device records of the system's and the process's own crashes, coexisting with any reporter, with the destination left to the app.
AstryxDailyMetrics react-native-performance measures marks and timings inside the running app; Firebase Performance and Sentry's performance monitoring measure sessions and upload them. None reads the system's own daily payload (MetricKit has no JavaScript surface); any route needs native code.
AstryxFrameRecorder Detox, Maestro, and Appium read element frames between steps; react-native-performance and the system's frame-rate tools report frame timing. None reads a view's on-screen frame at every displayed frame of an animation; per-frame presentation reads need native code. Test tooling only: Debug builds, reached through ./testing.

Writing rubric results

  • R1 narration: none; every requirement states what the platform does in the present tense.
  • R2 research in the record: none; "Why this exists" keeps one conclusion per module (whether the alternative needs native code, and the gap), with no survey, comparison table, or benchmark; the survey it rests on is in this description.
  • R3 evidence naming a change: none; Verification cells name the evidence layer (unit tests through ./testing doubles, XCTest, Simulator, device, release and privacy-manifest checks).
  • R4 rejected alternatives over one line or outside a decision: four, one line each, inside DEC-1 to DEC-4.
  • R5 pull request or issue references remaining: none.
  • R6 ruled open questions still listing options: the two placement questions (core or an opt-in capability; where the frame recorder ships) are answered by the placement and are out of the record; OQ1 and OQ2 (Android crash reports and frame recording) are unanswered and keep their options.
  • R7 project status (build status or work order): none beyond two gap lines in the R7 form: "FR2 gap: on iOS, list, clear, and crashForTest answer unsupported …" and "FR7 gap: a recording that stopped itself answers stop with the reason timed-out …".
  • Stage and Preview sweep: every Stage and Preview requirement, column, verification part, and clause is out of the record, which points to spec:AST-139 (Stage) and spec:AST-141 (Preview) in Non-goals; FR11 stays unused, and the open questions are numbered OQ1 and OQ2. R1 to R7 rerun over the whole record after the sweep: results as above.

Scope

Components: AstryxCrashReports, AstryxDailyMetrics, AstryxFrameRecorder, recordFrames, isFrameRecorderAvailable

  • This PR contains specification records only.
  • It records observable behavior and preserves equivalent internal implementations.
  • Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract.
  • Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
  • It records one intentional durable decision, not a rescue for a separable tagalong.
  • The canonical knowledge owner, affected current claims, and overlapping open work are named; any ownership collision is resolved or called out for human decision.
  • Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
  • Public text and attached files contain no internal company context.

Validation

  • pnpm check:knowledge (node scripts/check-knowledge.mjs): "Knowledge templates and records are aligned."; no error or status warning for this record.
  • Prettier --check: all matched files use Prettier code style.
  • git diff --check origin/main: clean.
  • Leak scan of the diff and this description: no hard hits; the only soft hits are the public pull request numbers in the dependency and merge-order lines.
  • pnpm specs:for is not runnable in this checkout (no install); skipped.

@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 18, 2026 6:29am UTC

Request Review

@astracat-bot

astracat-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🔄 In progress (for maintainers only) Nov 18, 2026, 6:20 AM UTC

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 18, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval waits on an engineering owner's decision on this draft contract and on five fixes to the record.

Owner decision: FR1–FR13 and DEC-1–DEC-4 are new requirements that no current record on main covers, so an engineering owner records approval by commenting /approve-spec <full head SHA> (the author may do so as an engineering owner), settling in particular the crash-report opt-in and on-device retention (FR3–FR5, DEC-2, DEC-3), the always-on daily metrics in the core (FR6, OQ1), and the Debug-only frame recorder behind ./testing (FR7, DEC-4).

Blocking:

  • FR1 says an absent module's wrapper answers no-module and lists only iOS for crash reports and daily metrics, but FR6 requires os for Android's latest() and FR11 makes both modules present in Astryx Stage, so FR1 should yield to those rules and list Astryx Stage.
  • FR7 has stop answer timed-out "with what it saw", but a timed-out failure carries no data under FR2's result shape, so make the self-stop an ok result with a timed-out field or drop the samples.
  • The "Why this exists" table surveys ten third-party tools, which architecture:knowledge-contracts INV10 keeps out of records, so move it to an artifact linked from this pull request, keep the conclusion in DEC-1, and correct the R2 rubric line.
  • DEC-1, FR6 and FR10 rest on spec:AST-132 DEC-5 and spec:AST-130 FR8 and FR18, which are not on main, and ./testing/behaviour is named as an existing entry that no record defines, so land this after those records and define or drop that entry.
  • The platform table's "one JSON file per report in Application Support", FR9's "one serial queue" and FR7's "searched for again only every few frames" fix internal mechanisms that no caller depends on, against the record's own Non-goals and the description's checklist, so state the observable property instead.

Non-blocking: a crash recorded by the signal or exception handler also returns later as a metrickit report with nothing linking the two, and the record keeps version() revision counters that the open foundation amendment removes.

Claims and files checked

Review mode: full; reason: no-earlier-review

  • Claim: the record defines the three diagnostics modules with their methods, results and reasons: verified (FR1, FR2).
  • Claim: crash reports stay off until a native opt-in and keep three sources whole for 14 days: verified (FR3).
  • Claim: the crash reporters chain to other reporters and hand the crash on: verified (FR4).
  • Claim: the test crash trigger needs both gates and release checks refuse it: verified (FR5).
  • Claim: daily metrics keep the newest payload and Android answers os: verified (FR6), but it conflicts with FR1 (first blocking finding).
  • Claim: nothing leaves the device: verified (FR8).
  • Claim: every contract starts at revision 1 with named features after it, and Astryx Stage pairs by a version floor: verified (FR10).
  • Claim: public platform API only: verified (FR12).
  • Claim: no record on main owns these contracts and the identifier is unused: verified for main and open pull request titles.
  • Claim: the foundation record's FR1 does not list diagnostics: verified.
  • Claim: the system-modules and media records are open drafts holding the cited requirements and decision: verified in their open pull requests; neither is on main.
  • Claim: two requirement gaps are recorded: verified (FR2 gap, FR11 gap).
  • Claim: the implementation lives in the package's platform layer: not verifiable here, as the React Native package is not in this repository's tree.
  • Claim: rubric results R1 and R3 to R7: verified; R2 "none": false (third blocking finding).
  • Claim: the pull request contains specification records only: verified.
  • Claim: every named internal mechanism names its dependent caller: false (fifth blocking finding).
  • Claim: verification names evidence layers without CI job topology: verified.
  • Claim: overlapping open work is named: partly, as the open foundation amendment that removes revision counters is not named.
  • Claim: no internal company context: verified.
  • Claim: the knowledge check, Prettier and whitespace checks pass: verified at this head.
  • File docs/specs/AST-137-react-native-diagnostics/spec.md: the five blocking findings and two notes above.

Automated review (maintainer link)

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval waits on an engineering owner's decision on this draft contract; the five earlier blocking findings are fixed and no blocking finding remains.

Owner decision: FR1–FR13 and DEC-1–DEC-4 are new requirements that no current record on main covers, so an engineering owner records approval by commenting /approve-spec <full head SHA> (the author may do so as an engineering owner), settling in particular the crash-report opt-in with whole, unscrubbed reports kept on the device for 14 days (FR3–FR5, DEC-2, DEC-3), the daily-metrics subscriber in every app's core while OQ1 stays open (FR6), and the Debug-only frame recorder behind ./testing (FR7, DEC-4).

The record cites spec:AST-130, spec:AST-132 and the open spec:AST-112 amendment, none of which is on main yet, so it should merge only after them, as the description says.

Non-blocking: FR2's list of synchronous members has an empty item where version() was removed (see the inline suggestion).

Claims and files checked

Review mode: full; reason: spec-record

  • Claim: the record defines the three diagnostics modules with their methods, results and closed reasons: verified (FR1, FR2).
  • Claim: results never throw, a Preview project gets not-allowed, and recordFrames is the one throwing call: verified (FR2).
  • Claim: crash reports stay off until a native opt-in, install before the first frame, and keep three sources whole for 14 days: verified (FR3).
  • Claim: the crash reporters chain to and hand on to every other reporter: verified (FR4).
  • Claim: the test crash trigger works only in a test build that declares it, and release checks refuse a shipped build that does: verified (FR5).
  • Claim: a recording that stops itself after 60 seconds answers ok with its samples and isTimedOut: true: verified (FR7).
  • Claim: daily metrics keep the newest payload only (scroll hitches, peak memory, median time to first frame), and Android answers os: verified (FR6), now consistent with FR1.
  • Claim: nothing leaves the device unless the app sends it, and the app scrubs and attributes what it sends: verified (FR8).
  • Claim: every contract is at revision 1 with no counter, later behaviour is a named feature, and Astryx Stage pairs through a version floor: verified (FR10); it follows the open foundation amendment.
  • Claim: public platform API only: verified (FR12).
  • Claim: the foundation record's FR1 does not list diagnostics: verified.
  • Claim: the system-modules and media records are open drafts holding the cited requirements and decision: verified; neither is on main.
  • Claim: no record on main owns these contracts and the identifier is free: verified for main and open pull request titles.
  • Claim: three gaps are recorded (FR2, FR7, FR11): verified.
  • Claim: the record merges after the system-modules, media and foundation-amendment records: verified as stated in the description.
  • Claim: the implementation lives in the package's platform layer: not verifiable here, as that package is not in this repository.
  • Claim: rubric results R1 to R7, including R2 "none" with one conclusion per module: verified.
  • Claim: the pull request contains specification records only: verified.
  • Claim: every named internal mechanism is intentionally public: verified; the storage layout, queue and search cadence are replaced by observable properties.
  • Claim: verification names evidence layers without CI job topology: verified.
  • Claim: no internal company context: verified.
  • Claim: the knowledge check, Prettier and whitespace checks pass: verified at this head.
  • File docs/specs/AST-137-react-native-diagnostics/spec.md: one non-blocking finding (FR2's empty list item); the five earlier blocking findings are fixed.

Automated review (maintainer link)

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval waits on an engineering owner's decision on this draft contract; no blocking finding remains, and FR2's list of synchronous members is fixed.

Owner decision: FR1–FR13 and DEC-1–DEC-4 are new requirements that no current record on main covers, so an engineering owner records approval by commenting /approve-spec <full head SHA> (the author may do so as an engineering owner), settling in particular the crash-report opt-in with whole, unscrubbed reports kept on the device for 14 days (FR3–FR5, DEC-2, DEC-3), the daily-metrics subscriber in every app's core while OQ1 stays open (FR6), and the Debug-only frame recorder behind ./testing (FR7, DEC-4).

The record cites spec:AST-130, spec:AST-132 and the open spec:AST-112 amendment, none of which is on main yet, so it should merge only after them, as the description says.

Non-blocking:

  • Miss: FR11 says Astryx Stage's list answers no reports without saying what an opted-out project gets, while FR3 answers not-declared there; see the inline suggestion.
Claims and files checked

Review mode: full; reason: spec-record

  • Claim: the record defines the three diagnostics modules with their methods, results and closed reasons: verified (FR1, FR2).
  • Claim: results never throw, a Preview project gets not-allowed, and recordFrames is the one throwing call: verified (FR2).
  • Claim: crash reports stay off until a native opt-in, install before the first frame, and keep three sources whole for 14 days: verified (FR3).
  • Claim: the crash reporters chain to and hand on to every other reporter: verified (FR4).
  • Claim: the test crash trigger works only in a test build that declares it, and release checks refuse a shipped build that does: verified (FR5).
  • Claim: a recording that stops itself after 60 seconds answers ok with its samples and isTimedOut: true: verified (FR7).
  • Claim: daily metrics keep the newest payload only (scroll hitches, peak memory, median time to first frame), and Android answers os: verified (FR6), consistent with FR1.
  • Claim: nothing leaves the device unless the app sends it, and the app scrubs and attributes what it sends: verified (FR8).
  • Claim: every contract is at revision 1 with no counter, later behaviour is a named feature, and Astryx Stage pairs through a version floor: verified (FR10); it follows the open foundation amendment.
  • Claim: public platform API only: verified (FR12).
  • Claim: the foundation record's FR1 does not list diagnostics: verified.
  • Claim: the system-modules and media records are open drafts holding the cited requirements and decision: verified; neither is on main.
  • Claim: no record on main owns these contracts and the identifier is free: verified for main and open pull request titles.
  • Claim: three gaps are recorded (FR2, FR7, FR11): verified.
  • Claim: the record merges after the foundation promotion and amendment and the sibling platform records: verified as stated in the description; all four are still open.
  • Claim: the implementation lives in the package's platform layer: not verifiable here, as that package is not in this repository.
  • Claim: rubric results R1 to R7, including R2 "none" with one conclusion per module: verified.
  • Claim: the pull request contains specification records only: verified.
  • Claim: every named internal mechanism is intentionally public: verified; storage layouts, queues and search cadence are stated as observable properties.
  • Claim: verification names evidence layers without CI job topology: verified.
  • Claim: no internal company context: verified.
  • Claim: the knowledge check, Prettier and whitespace checks pass: verified at this head.
  • File docs/specs/AST-137-react-native-diagnostics/spec.md: one non-blocking finding (FR11's opted-out Astryx Stage list answer); the earlier empty list item in FR2 is fixed.

Automated review (maintainer link)

Comment on lines +307 to +309
- `AstryxCrashReports`: present, with `isEnabled()` following the project's
opt-in; `list` answers no reports and `crashForTest` answers
`not-declared`, because Astryx Stage never crashes a project on purpose.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Miss (non-blocking): FR11 says list answers no reports, but FR3 makes an opted-out app's list answer not-declared, and FR11's verification fails a Stage answer that differs from the Simulator's. Say which answer an opted-out project gets.

Suggested change
- `AstryxCrashReports`: present, with `isEnabled()` following the project's
opt-in; `list` answers no reports and `crashForTest` answers
`not-declared`, because Astryx Stage never crashes a project on purpose.
- `AstryxCrashReports`: present, with `isEnabled()` following the project's
opt-in. An opted-in project's `list` answers no reports, and an opted-out
one's answers `not-declared` (FR3). `crashForTest` answers `not-declared`,
because Astryx Stage never crashes a project on purpose.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolved in c992dae: the record no longer states Astryx Stage behaviour (it points to spec:AST-139 in Non-goals), so FR11 is gone here; the suggested wording for an opted-out project goes with it to that record.

@imdreamrunner

Copy link
Copy Markdown
Contributor Author

Parked: these modules belong to an optional add-on package, which is not part of the core React Native library. The branch stays so this work can resume.

@github-actions
github-actions Bot deleted the spec/ast-137-react-native-diagnostics branch November 19, 2026 06:04

This branch was successfully deployed

1 active deployment
Preview — 9ad7ac93 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant