Repository navigation
spec(AST-137): React Native platform: Diagnostics (draft) - #12570
imdreamrunner wants to merge 6 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
AI review status for this pull request.
|
There was a problem hiding this comment.
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-moduleand lists only iOS for crash reports and daily metrics, but FR6 requiresosfor Android'slatest()and FR11 makes both modules present in Astryx Stage, so FR1 should yield to those rules and list Astryx Stage. - FR7 has
stopanswertimed-out"with what it saw", but atimed-outfailure carries no data under FR2's result shape, so make the self-stop anokresult with a timed-out field or drop the samples. - The "Why this exists" table surveys ten third-party tools, which
architecture:knowledge-contractsINV10 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-132DEC-5 andspec:AST-130FR8 and FR18, which are not onmain, and./testing/behaviouris 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
mainowns these contracts and the identifier is unused: verified formainand 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.
…nclusions only, observable properties
There was a problem hiding this comment.
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, andrecordFramesis 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
okwith its samples andisTimedOut: 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
mainowns these contracts and the identifier is free: verified formainand 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.
There was a problem hiding this comment.
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
listanswers no reports without saying what an opted-out project gets, while FR3 answersnot-declaredthere; 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, andrecordFramesis 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
okwith its samples andisTimedOut: 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
mainowns these contracts and the identifier is free: verified formainand 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 Stagelistanswer); the earlier empty list item in FR2 is fixed.
| - `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. |
There was a problem hiding this comment.
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.
| - `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. |
There was a problem hiding this comment.
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.
…ite AST-140 and AST-112 DEC-16
|
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. |
Depends on #12563 (
spec:AST-112as amended), #12594 (spec:AST-140, platform code rules), and #12553 (spec:AST-130). The record citesspec:AST-112FR1, FR4, FR5, FR7, FR15 and DEC-16,spec:AST-140FR1, FR3, FR5 and FR6, andspec:AST-130FR8 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-onlyAstryxFrameRecorder(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 andrecordFrames, 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 tospec:AST-130and 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'slaunchand memory) and FR18 (named features throughcontractFeatures). Referenced; unchanged.spec:AST-139(Astryx Stage) andspec: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 forAstryxCrashReports,AstryxDailyMetrics,AstryxFrameRecorder,recordFrames,crash,MetricKit,frame recorder: no record owns these contracts.AST-137,crash,metrics,diagnostics, andReact Native platform: only the sibling platform group drafts; AST-130 names this group as out of its scope. AST-137 is free onmain, 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:
./testing.not-declared;osandunavailable;unavailable,busy,not-recording).recordFramesis the one throwing call: a test step that cannot record fails, never passes with nothing checked.crashForTestcrashes only a test build that declares the trigger; release checks refuse a shipped build that does.okwith its samples andisTimedOut: true.os.Who uses it
AstryxCrashReportsAstryxCrashReports)AstryxDailyMetricsAstryxDailyMetrics)AstryxFrameRecorder./testing'srecordFramesRejected alternatives
Claim scope and non-goals
The record governs
AstryxCrashReports,AstryxDailyMetrics,AstryxFrameRecorder, and./testing'srecordFramesandisFrameRecorderAvailable. It leaves out whatAstryxPlatformInforeports (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
./testingentry (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 answersunsupportedinstead ofnot-declared(FR2), and a self-stopped recording answerstimed-outinstead ofokwithisTimedOut(FR7).Survey behind "Why this exists"
The record keeps one conclusion per module; the comparison it rests on:
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-handlercatches native exceptions on the device.AstryxDailyMetricsreact-native-performancemeasures marks and timings inside the running app; Firebase Performance and Sentry's performance monitoring measure sessions and upload them.AstryxFrameRecorderreact-native-performanceand the system's frame-rate tools report frame timing../testing.Writing rubric results
./testingdoubles, XCTest, Simulator, device, release and privacy-manifest checks).list,clear, andcrashForTestanswerunsupported…" and "FR7 gap: a recording that stopped itself answersstopwith the reasontimed-out…".spec:AST-139(Stage) andspec: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,isFrameRecorderAvailableValidation
pnpm check:knowledge(node scripts/check-knowledge.mjs): "Knowledge templates and records are aligned."; no error or status warning for this record.--check: all matched files use Prettier code style.git diff --check origin/main: clean.pnpm specs:foris not runnable in this checkout (no install); skipped.