Skip to content

spec(AST-112): runtime boundaries - #12998

Draft
imdreamrunner wants to merge 6 commits into
mainfrom
spec/ast-112-runtime-boundaries
Draft

imdreamrunner wants to merge 6 commits into
mainfrom
spec/ast-112-runtime-boundaries

Conversation

@imdreamrunner

@imdreamrunner imdreamrunner commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Runtime-boundary follow-ups to the draft spec:AST-112 record: Intl, unsupported platforms, an opt-in for the core's MetricKit subscriber, and no runtime method replacement in the core.

Exact decision needed

Whether these edits to the draft React Native foundation record stand:

  • DEC-10 and a new FR5 line: every component renders and works on a runtime without Intl; there, output that needs it (locale-aware number and plural formatting, for example) falls back to a simpler form. A component may use the platform's formatter through its native module where one exists, and none needs one to render. No Intl polyfill is installed as a global.
  • A new FR11 line, pointed to from Platform support: on a platform Astryx React Native does not support (for example macOS through react-native-macos) the package logs one development warning at startup naming the platform, and never draws silently empty icons or charts.
  • New DEC-21 with an FR3 line: on iOS the core adds no MetricKit subscriber unless the app opts in through its capability list; a library collects no app-level diagnostics the app did not ask for.
  • New DEC-22 with FR4 lines: the core replaces no method of a UIKit or React Native class at run time, so Astryx stays compatible with the other libraries in an app and with React Native upgrades; it fixes what it owns inside its own hosts. The stack host resets React Native's right-to-left mirror on the scroll view it owns; on iOS the library's modal surfaces present only through the presentation host, with no React Native Modal path; the generated app shell and the Expo plugin write the explicit sign-in URL claim call, with no interceptor; and clear on sign-out covers React Native's networking session, through React Native's public session-configuration hook, and Astryx's own sessions, while the app's shared URL cache stays the app's own (an app with its own session-configuration provider opts in explicitly).

Existing authority searched

  • spec:AST-112 on main: DEC-10 (importing the package changes no globals), Platform support, Open questions, and the Verification table.
  • spec:AST-140 FR1 and FR7 (how native code reaches JavaScript; the testing surface's setup), which DEC-10 already points to.
  • spec:AST-140 FR9 on main (the methods of system and React Native classes stay as they are), which DEC-22 agrees with; this pull request does not edit spec:AST-140.
  • The React Native package's current code, read for the gap lines: the core replaces the shared URL cache at load and adds its MetricKit subscriber in every app; it replaces methods on React Native's scroll view and Modal host, on UIKit's view-controller presentation, and, for the opt-in URL interceptor, on the delegate setters and URL-opening methods; number formatting builds Intl.NumberFormat without a fallback, a plural-rules polyfill installs a global Intl.PluralRules where the runtime has none, Avatar initials fall back to code points without Intl.Segmenter, and no unsupported-platform warning exists.
  • Terms searched: Intl, Hermes, react-native-macos, Platform.OS, URLCache, MetricKit, swizzl. spec(AST-112): follow-ups after merge #12974 (spec:AST-112 follow-ups, open draft) edits the same record in separate sections (the non-goals, FR2's row, FR20, FR21, DEC-3, OQ8 and two Current-state impact entries); neither pull request edits text the other changes.

Decision

docs/specs/AST-112-react-native-foundation/spec.md (spec:AST-112):

  • DEC-10 and FR5: every component renders and works without Intl, with a simpler form for output that needs it; the platform's formatter may be used where one exists; no global Intl polyfill.
  • FR11 (and Platform support): one development warning at startup on an unsupported platform, naming it; no silently empty icons or charts.
  • Gap lines: no unsupported-platform warning today (FR11); number formatting builds Intl.NumberFormat without a fallback, and the package installs a global Intl.PluralRules on a runtime without one, and Avatar's initials fall back to code points without Intl.Segmenter (FR5); the core subscribes to MetricKit in every app that links it (FR3); and five FR4 gaps: the scroll-view method exchange; the Modal-host replacement and the React Native Modal fallback on iOS; the view-controller presentation replacement for a hosted-project container, code that leaves the core; the opt-in URL interceptor; and the shared URL cache replacement.
  • DEC-21 (Decider: imdreamrunner, 2026-11-19), with an FR3 line and a DEC-21 verification row: no Astryx subscriber in an app that did not opt in, exactly one in an app that did.
  • DEC-22 (Decider: imdreamrunner, 2026-11-19), with FR4 lines, a DEC-22 verification row (a source check that the core carries no method exchange, set-implementation, or replace-method call on a UIKit or React Native class) and an FR4 row for the cache scope (the app's shared URL cache stays the app's own; nothing in flight lands after a clear).
  • Verification: a DEC-10 row (a source check that every Intl read has a fallback; a number and a plural formatted without Intl; Avatar initials without Intl match component:Avatar FR3's) and an FR11 row (a development-warning test under an unsupported Platform.OS).

Rejected alternatives

None recorded in the record.

Claim scope and non-goals

Only the follow-ups above, all in spec:AST-112. No requirement or decision is removed, and no other record changes.

Evidence and implementation relationship

The record is a specification only and has no implementation in this pull request. The two gap lines state where the current package differs.

Writing rubric results

  • R1 narration: none; the edits are in the present tense.
  • R2 research in the record: none; each gap line states one current mismatch without history.
  • R3 evidence naming a change: none.
  • R4 rejected alternatives over one line or outside a decision: none; no Rejected: lines.
  • R5 pull request or issue references remaining: none in the record.
  • R6 ruled open questions still listing options: none; no open question is added.
  • R7 project status (build status or work order): the package's differences are stated as gap lines.

Scope

  • 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 artifacts contain no internal Meta context.

Validation

  • node scripts/check-knowledge.mjs: knowledge templates and records are aligned (exit 0).
  • Prettier: --check clean on the record.
  • git diff --check: clean.

@vercel

vercel Bot commented Nov 19, 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 19, 2026 9:47pm UTC

Request Review

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

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🔄 In progress (for maintainers only) Nov 19, 2026, 9:47 PM UTC

@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.

On hold for an engineering owner's decision. Both records this pull request edits are draft, and this head writes requirements that no current record states, so approval needs an engineering owner to record the decision by commenting /approve-spec <full head SHA> on this pull request; the author may do so if they are an engineering owner. What must be settled: DEC-10's rule that the package's own code does not depend on Intl, the Platform support warning on an unsupported platform, DEC-21 (the MetricKit subscriber is opt-in), DEC-22 (a method replacement calls through, installs once and keeps other libraries' replacements working), and AST-140 FR9's exception for such a replacement. Two fixes are needed whatever that decision is:

  • spec:AST-112 DEC-22 and its FR4 line bind only "a method of a class it does not own, from UIKit or React Native", while spec:AST-140 FR9's new exception covers the methods of every system class, so a replacement on a system class outside UIKit is admitted by FR9's verification row and defined by neither record — use one class scope in the FR4 line, DEC-22 and FR9.
  • Platform gap: (docs/specs/AST-112-react-native-foundation/spec.md:703) and DEC-10 gap: (:705) are not in the <FR or INV id> gap: <observable mismatch> form that architecture:knowledge-contracts INV32 allows, and the new Intl rule exists only in DEC-10's prose while DEC-10's other rules are FR5 lines — give both rules an FR home (FR5 for Intl, FR11 for the unsupported platform) and write each gap against it.

Two smaller points: the FR4 gap paragraph sits between FR4's bullets, so FR4's last two bullets read as a separate list after it; and the DEC-10 verification row fails "initials that are wrong" for a name with combining marks and an emoji without saying what the right initials are, although a code-point fallback splits such names.

Claims and files checked

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

  • Edits land in spec:AST-112 DEC-10, Platform support, FR3, FR4, the verification table and the open questions, plus one spec:AST-140 FR9 clause and its row: verified against the diff.
  • No requirement or decision is removed and no other record changes: verified; the diff adds lines and rewords one FR9 clause only.
  • No other open pull request edits these parts of spec:AST-112: verified; the other open pull request on this record edits its Intent, Current-state impact, DEC-3 and OQ8, and the two heads merge cleanly.
  • Writing rubric R5 (no pull request or issue references in the record) and R6 (OQ9 is new, unanswered and keeps its options): verified in the record text.
  • Writing rubric R7 (the package's differences are stated as gap lines): partly false — two of the four gap lines are not in the allowed gap form.
  • node scripts/check-knowledge.mjs passes: verified by running it on this head; it reports records aligned and warns about no line of either record.
  • Prettier --check clean on the records, and git diff --check clean: both verified on this head.
  • The pull request contains specification records only, with no changeset: verified; two files, both records.
  • The statements about the package's current behavior (the MetricKit subscriber, the two replacements that do not call through, Intl.NumberFormat without a fallback, the global plural-rules polyfill, the missing platform warning, the shared URL cache): unverified — @astryxdesign/react-native is not in this repository, so no code backs or contradicts them here.
  • Files: docs/specs/AST-112-react-native-foundation/spec.md (findings above), docs/specs/AST-140-react-native-platform-code/spec.md (first finding 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.

On hold for an engineering owner's decision, with one fix needed.

spec:AST-112 is a draft record, and this head adds requirements that no current record states, so approval needs an engineering owner to record the decision by commenting /approve-spec <full head SHA> on this pull request; the author may do so as an engineering owner. What must be settled: FR5 and DEC-10's rule that components work without Intl, FR11's warning on an unsupported platform, FR3 and DEC-21's MetricKit opt-in, and FR4 and DEC-22's rule that the core replaces no UIKit or React Native method, including what FR4's sign-in claim and clear on sign-out are.

Blocking, whatever that decision is:

  • The DEC-10 verification row (spec.md:857) requires initials without Intl to be the first code point of each word, which splits the accented letters and emoji sequences that component:Avatar FR3 keeps whole ("grapheme clusters are never split"), so the row should expect component:Avatar FR3's initials instead.

The inline comments carry five smaller notes: name DEC-21's opt-in, cite spec:AST-140 FR9 in DEC-22, define the sign-in call and clear on sign-out, drop "that code leaves the core", and key the warning and cache rows to FR11 and FR4.

Claims and files checked

Review mode: full; reason: spec-record

  • Claims:
    • The DEC-10 amendment and a new FR5 line make every component work without Intl, with a simpler-form fallback and no global polyfill: verified (spec.md:307-309, :972-977).
    • A new FR11 line, pointed to from Platform support, adds one development warning on an unsupported platform: verified (:429-432, :734-735).
    • DEC-21 with an FR3 line makes the core's MetricKit subscriber opt-in: verified (:170-173, :1081-1089).
    • DEC-22 with FR4 lines says the core replaces no UIKit or React Native method and fixes what it owns in its own hosts: verified (:232-247, :1091-1100).
    • Gap lines for FR11, FR5, FR3 and five for FR4: verified (:178, :261-273, :340-342, :434).
    • Verification rows for DEC-10, the platform warning, DEC-21, DEC-22 and the cache scope: verified (:857-861).
    • DEC-22 agrees with the platform-code record's FR9, which this pull request does not edit: verified; that record is untouched, and its FR9 scope is wider.
    • No requirement or decision is removed and no other record changes: verified (one file; the two removed lines are rewritten with their text kept).
    • The rubric's project-status result reports none: false in part, because the FR4 gap at :268 ends "that code leaves the core".
    • Knowledge validation, Prettier and whitespace checks pass: not rerun.
  • Files:
    • docs/specs/AST-112-react-native-foundation/spec.md: one blocking finding (the DEC-10 row) and five non-blocking notes.

Automated review (maintainer link)

| FR21 | `exports` map check; a capture of each component that takes `render`, with `system`, `drawn`, and `auto` on both platforms; a theme with `platforms.ios` and `platforms.android` glass intent on both platforms | each `render` value; each `surface` value on `Button` and `IconButton`, drawn and system-drawn; a native theme `material` entry | A public JavaScript glass or material component, a `render` value that draws with the wrong side, a drawn button that ignores its `surface`, a system-drawn button whose platform style does not match its `surface`, a surface whose look ignores the theme's `material`, or a look that the props and the native theme cannot express |
| FR22 | Review of each native module's interface; the conformance tests on the engines React Native supports | each native module; each engine | A contract or test that depends on one engine, or an interface that names one engine's internals |
| FR23 | Review of where `NavigationStack`, `Screen`, `useScreenScrollProps()`, and the stack navigator are exported; the CI lane of a pull request that changes the lab folder | each of the four names; a pull request that changes only `packages/react-native/lab/`; web's `NavigationStack` leaving Lab | One of the four names in a stable entry while web's `NavigationStack` is in Lab, one outside `./unstable/*` while in the lab, or a lab pull request on the Lab-only lane |
| DEC-10 | A source check that every `Intl` read has a fallback; Avatar initials rendered under a runtime without `Intl` | each `Intl` read in the package's own code; a name with combining marks and an emoji; a number and a plural formatted without `Intl` | An `Intl` read without a fallback, a component that does not render or work without `Intl`, initials without `Intl` other than the first code point of the name's first and last words, or a global `Intl` polyfill |

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.

Blocking. Without Intl, this row requires initials to be "the first code point of the name's first and last words". component:Avatar FR3 (current) keeps grapheme clusters whole, skips leading punctuation and uppercases, and spec:AST-082 FR3 lets a platform offer only props it fully honours. For "Zoë Ångström" with decomposed accents, the row requires "ZA" where core shows "ZÅ", and for "👩🏽‍💻 Kim" a bare "👩". Have the row fail "initials without Intl that differ from component:Avatar FR3". The platform's own text segmentation through the native module (which DEC-10 already allows), or a fallback that keeps clusters, produces them. If React Native must differ, an owner amends component:Avatar FR3 instead.

Comment on lines +238 to +247
- The generated app shell and the Expo package's configuration plugin
write the explicit call that hands an opened URL to the sign-in claim;
an app with its own native projects makes that call itself. No
interceptor stands in for it.
- The HTTP cache guarantees of clear on sign-out, under which nothing in
flight lands after a clear, cover React Native's networking session,
through React Native's public session-configuration hook, and Astryx's
own sessions. The app's shared URL cache stays the app's own. An app
that sets its own session-configuration provider opts in to these
guarantees explicitly.

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.

Non-blocking: no record, on main or in this pull request, defines "the sign-in claim", "the explicit call that hands an opened URL" to it, or "clear on sign-out" and its "HTTP cache guarantees". So astryx rn shell, the Expo plugin and the FR4 row at :861 have nothing to build or check against. Cite the record that owns them, or state the call (and whether it is part of the core's app-lifecycle entry, :211-223) and what the clear removes.

Comment on lines +170 to +173
- On iOS the core adds no MetricKit subscriber unless the app opts in to it
through its capability list, as it opts in a capability: an app that did
not opt in has no Astryx subscriber, and an app that did has exactly one
(DEC-21).

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.

Non-blocking: the capability list holds capabilities (FR5's entries, FR7's table), and the generators write opt-ins from it (FR4), but no entry is named for the MetricKit subscriber. Neither an app nor astryx rn shell can write this opt-in, and the DEC-21 row cannot build its "with the opt-in" app. Name the entry, and say whether it is a capability.

Comment on lines +232 to +233
- The core replaces no method of a UIKit or React Native class at run time
(DEC-22). It fixes what it owns inside its own hosts:

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.

Non-blocking: this restates draft spec:AST-140 FR9 with a narrower scope: "a UIKit or React Native class", against FR9's "system classes, React Native's classes, and other libraries' classes". This record's Current-state impact makes AST-140 FR9 the owner of coexistence (:793-799). Cite spec:AST-140/FR9 here and in DEC-22, so a reader of this record does not take a Foundation or third-party method as allowed.

Comment on lines +267 to +268
FR4 gap: the core replaces UIKit's view-controller presentation method for a
hosted-project container; that code leaves the core.

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.

Non-blocking: "that code leaves the core" states work to come, and architecture:knowledge-contracts INV32 allows a gap only as an observable mismatch. Drop the clause, or write it as an FR4 requirement if hosted-project containers belong outside the core.

Comment on lines +858 to +861
| Platform | A development-warning test under an unsupported `Platform.OS` | `Platform.OS` set to `macos` and to `windows` | No warning, more than one warning, a warning that does not name the platform, or an icon or chart that draws empty without a warning |
| DEC-21 | A launch test on iOS of the subscribers MetricKit holds, in an app built with and without the opt-in | an app that did not opt in; an app that opted in; a second launch step in the same process | An Astryx subscriber in an app that did not opt in, none or more than one in an app that did, or an app subscriber removed or replaced |
| DEC-22 | A source check of the core's iOS code | each file in the core | A method exchange, set-implementation, or replace-method call on a UIKit or React Native class |
| FR4 | A launch test on iOS of the shared URL cache; a clear on sign-out with requests in flight over React Native's networking and Astryx's own sessions | the default session-configuration provider; an app's own provider with and without the opt-in | The app's shared URL cache replaced, a response that lands after a clear, or an app's own provider overridden without its opt-in |

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.

Non-blocking: the warning's rule is now an FR11 line (:429-432), so key this row FR11 or fold it into FR11's row at :845. Also fold the cache row at :861 into FR4's row at :838, so each contract has one row.

This branch was successfully deployed

1 active deployment
Preview — 370b88b9 Deployed Nov 19, 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