@latchway/react-native 0.0.0-bootstrap.0 → 1.1.0

package/docs/architecture.md

@@ -0,0 +1,145 @@
+# React Native SDK architecture
+
+## Dependency and trust boundary
+
+```text
+React Native application
+  └─ @latchway/react-native
+       ├─ @latchway/client 1.0.0 (errors and shared transport concepts)
+       ├─ Latchway/AppAttest 1.0.0 (iOS)
+       ├─ Latchway/AppExtensions 1.0.0 (optional Debug extension target)
+       └─ dev.latchway:latchway-okhttp + latchway-play-integrity 1.0.0 (Android)
+```
+
+The core repository owns OpenAPI, error codes, attestation binding, DPoP behavior, and compatibility. This package owns the handwritten React Native API, fetch integration, TurboModule schema, cross-instance lease, abort propagation, stable error projection, and redacted diagnostics. Native SDKs exclusively own installation keys, secure session persistence, platform attestation, DPoP signing, and native single-flight.
+
+The gateway, not the SDK, derives user, organization, plan, trust, routing,
+pricing, and quota facts. The SDK never receives an upstream provider
+credential or treats application-supplied values as trusted server facts.
+
+## Contract ownership
+
+The Latchway core repository exclusively owns the client OpenAPI, error-code
+registry, protocol compatibility manifest, canonical attestation binding, DPoP
+vectors, canonical request examples, and checksummed contract bundle. A
+contract update must verify checksums, update `contract.lock`, regenerate only
+internal types, rerun shared vectors, and pass conformance against the exact
+core revision. Generated bridge and wire types do not become public API.
+
+## Operation flow
+
+1. JavaScript validates the origin, feature, configuration, request state, and decoded query names; provider-credential names fail before identity acquisition or dispatch.
+2. The application identity callback returns an external identity JWT.
+3. The TurboModule passes that JWT transiently to the native SDK while native session work runs.
+4. Native repeats the exact origin and allowed-path checks, establishes or refreshes a device-bound session, signs a DPoP proof, attaches native-owned protocol headers, and dispatches through its private URLSession or OkHttp client.
+5. Native refuses redirects, retains the credential-bearing request and response task, and returns only an opaque response identifier, status, and allowlisted safe headers.
+6. A WHATWG `ReadableStream` pulls bounded base64 response chunks through the TurboModule. Pull demand supplies bridge backpressure; abort, reader cancellation, EOF, client disposal, and invalid metadata all finish or cancel the native handle. JavaScript never clones or replays an authenticated request. Android's locked authenticator and iOS's locked feature transport exclusively own the contract-safe, one-time pre-dispatch retry; iOS bounds rejection classification to 64 KiB before any response bytes become visible.
+
+Authorization, DPoP, access tokens, refresh tokens, private keys, and attestation evidence never appear in a native return value. Response bodies are application data, not credential envelopes, and remain incrementally delivered rather than eagerly buffered.
+
+The containing application's root client owns the public descriptor lifecycle:
+prepare, replace, descriptor diagnostics, descriptor revoke, and whole-family
+retirement. Descriptors are normalized and snapshotted before any identity
+await; native results must match the same snapshot. Identity is acquired only
+transiently for prepare, replace, revoke, and family retirement. Root-side
+component diagnostics are identity-free. A 65,536-byte JavaScript serialization
+limit keeps oversized descriptor sets from reaching the native bridge.
+
+The component path uses a separate extension-process client, not the containing
+app's root client or lease. JavaScript running inside a signed `.appex` can
+supply one validated public descriptor; native configuration rejects a
+containing-app process, selects `.reactNativeIOS`, and retains a
+`LatchwayExtensionClient` with no direct App Attest provider. iOS extensions
+cannot call `DCAppAttestService.generateKey`, and the containing application
+must not attest on their behalf. The extension can use only independently
+keyed, component-scoped delegated sessions. React Native v1 exposes no
+JavaScript component request operation. A second bridge operation returns only
+`LatchwayComponentDiagnostics`; direct-attestation trust-source decoders are
+retained for protocol compatibility but are not reachable proof claims. The
+identity callback is not invoked, and component credentials and DPoP material
+never cross the TurboModule. Both platforms report `attestation_unsupported`
+for the legacy direct operation.
+
+The example App Intents extension has no React Native runtime or TurboModule
+bridge. Its Debug target optionally links `Latchway/AppExtensions` and calls the
+native extension client directly to prove an independently keyed delegated
+session and one fully consumed bounded Responses request. The root publishes a
+nonsecret exact-run shared-Keychain challenge immediately before waiting. The
+intent captures it before client construction, rechecks it immediately before
+echoing the run in a bounded receipt, and cannot publish for a superseded run.
+The containing app accepts only its native-captured exact run and deletes both
+challenge and receipt before descriptor-bound family retirement and sign-out;
+abort also deletes both artifacts. This is local integration proof. In Release the
+AppExtensions pod is absent, no executable Latchway client path is compiled,
+and the intent fails closed. Both variants retain distinct root/extension
+bundle identities and provisioning profiles, private-first/shared-second root
+Keychain entitlements, and a shared-only extension entitlement. The root's
+first/default group keeps its key, identity, and session state outside the
+extension's reach.
+
+The bridge intentionally implements a bounded fetch subset: method, headers,
+an at-most-8-MiB buffered request body, cancellation, response metadata, and a
+pull-driven response stream. Browser cookie/cache modes, service workers,
+redirect following, streaming uploads, response trailers, and native response
+URL metadata are outside this transport. Framework compatibility therefore
+depends on a real custom-fetch seam and the framework's React Native support;
+the presence of `fetchFor` alone is not a version-support claim.
+
+`fetchFor(feature)` also maps the canonical safe
+`X-Latchway-Request-ID` response header to the conventional `X-Request-ID`
+alias without reading the body, so provider SDK failures retain server
+correlation. The native runtime remains the framework identity reported to the
+gateway (`react-native-fetch`); an underlying JavaScript library cannot spoof a
+different SDK/framework pair through caller headers.
+
+Feature binding is also protocol binding: a Responses feature cannot dispatch
+Chat Completions, Embeddings, or Anthropic Messages. A consumer set spanning
+those protocols constructs a separate `fetchFor` transport for each configured
+feature instead of multiplexing incompatible endpoints through one identifier.
+
+## Coordination
+
+A module-global root lease map is keyed by native-module identity plus gateway/application/environment scope. A separate component lease map adds the component definition and never aliases the root map. Equivalent clients reuse one native client and configuration promise; conflicting security configuration for an active scope is rejected. Reference-counted disposal drops the native object only after the last JavaScript client leaves. The native iOS actor and Android coordinator/mutex prevent session establishment and refresh stampedes.
+
+Native persistence namespaces include `react_native_ios` or `react_native_android`. The bridge configures the paired runtime identity, so challenge/grant platform and `X-Latchway-SDK: react-native` cannot disagree. Native compatibility JSON is checked against released contract 1.0.0 and current wire protocol 2 before any operation.
+
+## TurboModule boundary
+
+The handwritten spec carries root and component configuration as distinct
+operations, a bounded request description, the root client's transient
+application identity token, opaque response-handle start/read/close operations,
+quota/diagnostic results, public component descriptors for lifecycle and
+delegated-session compatibility, cancellation, and disposal. Root lifecycle
+mutations carry identity transiently; root-side and extension-side component
+diagnostics do not. The legacy direct-attestation operation remains
+ABI-compatible but fails closed. Extension-process component operations have no
+identity-token argument. The spec has no authorization-envelope operation and
+does not return or accept provider attestation evidence, Play request hashes,
+App Attest client-data hashes, session tokens, DPoP proofs, or key material.
+Generated Objective-C++ and Java specs are disposable codegen output, not
+public API.
+
+## Native dependencies
+
+Published package metadata pins release coordinates. CocoaPods consumes `Latchway/AppAttest` 1.0.0. Gradle consumes `dev.latchway:latchway-okhttp:1.0.0` and `dev.latchway:latchway-play-integrity:1.0.0`. Development may point `LATCHWAY_NATIVE_REPOSITORY` or `-PlatchwayNativeRepository` at a locally published Maven repository; local file links never enter npm metadata.
+
+## Diagnostics and errors
+
+Diagnostics contain version compatibility, platform, secure key-storage category, attestation support/provider, session state/expiration, installation ID/status, server version, and last request/error identifiers. Component diagnostics add only family/component IDs, public definition/access-group identifiers, key/session/grant availability, trust provenance/expiry, and a containing-app action flag. Native key IDs, JWK thumbprints, tokens, proofs, and evidence are excluded. Native errors are bounded, control-character stripped, secret-pattern redacted, and mapped to the shared `LatchwayError` taxonomy. A server-originated native error must carry the exact `https://docs.latchway.dev/errors/<hyphenated-code>` documentation URL; missing or mismatched links fail closed. `operation_indeterminate` alone carries a required canonical reconciliation ID through both native bridges; malformed, missing, contradictory, or otherwise attached operation metadata fails closed.
+
+## Verification boundary
+
+Unit and Node conformance tests own public request shaping, fail-closed
+credential-output checks, response pull/backpressure, error projection,
+cancellation, coordination, strict-CSP behavior, and
+canonical vectors. Reproducible code generation proves the handwritten schema
+remains valid. Native consumer builds prove released dependency resolution and
+bridge compilation. Physical-device conformance proves real App Attest and Play
+Integrity behavior, session rotation, quota, streaming, diagnostics, and
+revocation against the exact core image.
+
+## Non-goals
+
+This package does not own server policy, provider routing, quota enforcement,
+user-authentication UI, AI request modeling, upstream secrets, native
+cryptography, native attestation verification, or an independent session store.

package/docs/conformance.md

@@ -0,0 +1,68 @@
+# Conformance
+
+Node conformance validates JavaScript request shaping with the explicit testing bridge, malicious credential-field output rejection, native response pull/backpressure, strict-CSP safety, redaction, cancellation, version mismatch, cross-instance coordination, and canonical contract fixtures. It does not emulate hardware trust or assert that a production native transport attached a valid proof.
+
+The framework suite under `Conformance/framework` uses 16 applicable stable
+`FW-*` case IDs from the JavaScript SDK suite and binds them to the canonical
+`react-native-fetch` registry entry. It executes, rather than merely imports,
+the exact OpenAI 7.8.0, Vercel AI 7.0.85, and LangChain OpenAI 1.5.10 consumer
+paths. RN-specific `RN-FW-ANTHROPIC-001` separately runs
+`@ai-sdk/anthropic` 4.0.46 against `/v1/messages`, without claiming a canonical
+Anthropic framework registry entry. The official `@anthropic-ai/sdk` 0.120.0
+client is recorded as unsupported because its credential-chain Node filesystem
+imports fail an actual Metro bundle. The deterministic native-boundary fixture
+returns protocol-shaped Responses, Chat Completions, Anthropic Messages,
+embeddings, SSE usage, tool calls, structured output, quota failures, provider
+failures, and retry responses. Tests prove feature binding, safe headers,
+request-ID correlation, cancellation, fresh native operation IDs for framework
+retries, placeholder stripping, exact-origin refusal, and isolation from global
+fetch. The runnable consumer factory requires distinct Responses, Chat,
+Embeddings, and Anthropic feature identifiers because one active Latchway
+feature is bound to exactly one gateway protocol.
+
+`RN-FW-REFRESH-001` separately proves the public explicit-refresh operation
+followed by a framework request. It is intentionally not reported as shared
+`FW-BEH-006`: automatic recovery from a pre-dispatch expired native session is
+owned by the platform SDK and requires native/device evidence.
+
+`RN-FW-OPAQUE-001` proves the bounded `/proxy/{feature}/...` pathway keeps its
+feature binding through native dispatch. None of the RN-only cases extends the
+shared `FW-*` registry set.
+
+This suite deliberately does not manufacture DPoP proofs, refresh credentials,
+or platform attestation in JavaScript. Fresh-proof generation and native
+pre-dispatch retry classification remain native SDK/device evidence. The local
+framework result therefore supports the registry's `experimental` state; it is
+not hosted or physical-device release evidence.
+
+Real platform conformance requires the exact core image and real provider configuration:
+
+- iOS: App Attest development and production applications on physical devices; session creation, assertion reuse, nonce, refresh rotation, quota, streaming, diagnostics, and revocation.
+- Android: Play-distributed application with Play Integrity standard requests; hardware/StrongBox policy variants, nonce, refresh rotation, quota, streaming, diagnostics, and revocation.
+- Both: identity token expiry/reauthentication, installation platform validation, no secret material in errors/diagnostics, and published native dependency resolution.
+
+Provider credentials and signing material belong in protected CI/device infrastructure and are never committed. Missing provider credentials block device conformance only; they do not justify fake evidence or trusted identity fields.
+
+The production TurboModule intentionally cannot expose or mutate DPoP/session
+credentials for a JavaScript evidence harness. Replay, proof tamper, session
+credential rotation, and protocol-header mutation therefore have to be taken
+from the separately linked native SDK physical-device reports. The v2 raw
+React Native record omits those native-only claims. Its protected finalizer
+validates the hash-pinned platform-native report, imports only the five exact
+allowlisted proof objects, and rejects missing, failed, renamed, extended, or
+coordinate-substituted proofs. The React Native report remains ineligible
+unless all of its own runtime checks pass (eight on iOS, including direct
+assertion reuse; seven on Android) and every imported proof passes.
+
+The repository's native source jobs build official React Native 0.82 iOS and
+Android hosts against the exact locked SDK source releases. The published
+dependency jobs repeat those builds with local CocoaPods paths and Maven
+repositories removed. Neither is physical-device attestation evidence.
+
+Before v1 is called device-conformant, retain redacted run evidence for each
+platform/provider/environment combination covering installation creation,
+session reuse, identity expiry and reauthentication, nonce recovery, refresh
+rotation, quota, an SSE stream, diagnostics, revocation, and a post-revocation
+re-enrollment. The evidence must name the application release, device/OS,
+gateway image digest, contract bundle hash, SDK package versions, and request
+IDs without including tokens, proofs, keys, or raw attestations.

package/docs/langchain.md

@@ -0,0 +1,135 @@
+# LangChain on React Native
+
+Use `@latchway/react-native@1.1.0` for native authenticated transport and
+`@latchway/langchain@1.1.0` for the optional LangChain adapter. No provider key
+belongs in the application. Secure Enclave/Keystore, App Attest/Play Integrity,
+DPoP and refresh credentials stay native.
+
+## Install
+
+The tested baseline is React Native 0.82 / React 19.1, New Architecture:
+
+```sh
+npm install --save-exact @latchway/react-native@1.1.0 @latchway/langchain@1.1.0 \
+  @latchway/client@1.0.0 @langchain/core@1.2.9 @langchain/openai@1.5.10 openai@7.8.0
+cd ios && pod install && cd ..
+```
+
+Keep the lockfile. LangChain is not a dependency of the base React Native SDK.
+The native dependencies remain the public iOS/Android SDKs 1.0.0. Normal native
+signing, Firebase/other identity and gateway platform policy setup still applies.
+
+## Two explicit setup lines
+
+Put the bootstrap **first** in the application entrypoint, before importing
+React Native, Latchway, LangChain or any stream-dependent application module:
+
+```js
+import '@latchway/react-native/polyfills';
+import {AppRegistry} from 'react-native';
+import App from './App';
+```
+
+Use the optional compiler helper in `babel.config.js`:
+
+```js
+const {withLatchwayBabel} = require('@latchway/react-native/babel');
+module.exports = withLatchwayBabel({
+  presets: ['module:@react-native/babel-preset'],
+});
+```
+
+Use standard Metro; no resolver override, source alias or local SDK link is
+needed. Rebuild the native app after installation. Clear Metro's cache if it
+still resolves the old 1.0.0 source entry.
+
+The bootstrap installs missing async symbols before stream dependencies,
+incremental UTF-8 decoding, web streams, random values and abort compatibility.
+It only replaces URL when a capability probe fails, preserves working globals,
+and never replaces fetch or native security. The standard SDK import does not
+initialize globals. The decoder currently uses the pinned, deprecated
+`text-encoding@0.7.0` implementation for incremental decoding; this is a known
+maintenance dependency, not a claim of comprehensive runtime compatibility.
+
+The Babel helper enables `noClassCalls` and the export-namespace transform while
+preserving the rest of your config. Classes must still be constructed with
+`new`; LangChain's own type checks are not removed.
+
+## Create a model
+
+Create `latchway` using the ordinary SDK configuration and your current user's
+identity-token callback. Then pass that client directly—no transport wrapper:
+
+```ts
+import {createLatchwayResponsesModel} from '@latchway/langchain';
+
+const model = createLatchwayResponsesModel({
+  latchway,
+  feature: 'assistant',
+  reasoning: {effort: 'none'}, // only if your configured model supports this
+  chatOptions: {maxTokens: 1024},
+});
+const controller = new AbortController();
+for await (const chunk of await model.stream('Explain Latchway', {
+  signal: controller.signal,
+})) {
+  // Render text chunks; retain original messages for usage/callback metadata.
+}
+// controller.abort() cancels native networking too.
+```
+
+The feature must route `openai_responses`, with the matching trusted accounting
+profile, on gateway 1.0.2+. The server selects the physical model. The helper
+does not guess reasoning capabilities from the placeholder model alias: omit
+`reasoning` for routes that do not accept it. Stateless storage settings do not
+guarantee retention behavior across all upstream providers.
+
+For an `openai_chat` feature use the existing `createLatchwayChatOpenAI` instead.
+Both factories default to no automatic framework retries. Native pre-dispatch
+session recovery is separate; uncertain provider dispatches must not be replayed
+casually. Explicit `chatOptions.maxRetries` is an application policy choice.
+
+## Tools and local history
+
+```ts
+import {bindLatchwayTools, toLatchwayReplayMessage} from '@latchway/langchain';
+import {HumanMessage, type BaseMessage} from '@langchain/core/messages';
+
+// weather is your ordinary LangChain tool; the SDK never executes tools for you.
+const modelWithTools = bindLatchwayTools(model, [weather]);
+const history: BaseMessage[] = [new HumanMessage('Weather in Singapore?')];
+const answer = await modelWithTools.invoke(history);
+const replay = toLatchwayReplayMessage(answer);
+history.push(replay);
+// Dispatch only an allowlisted tool with validated arguments. Append the
+// returned ToolMessage, preserving the model's tool_call_id, then invoke again.
+```
+
+The binding helper
+defaults to `strict:true` and `parallel_tool_calls:false`; ordinary LangChain
+options can override these deliberately. Supply strict-compatible schemas
+(all required fields, `additionalProperties:false`; nullable instead of optional
+properties when necessary).
+
+Use `toLatchwayReplayMessage` only after a successful complete response (or
+aggregating all stream chunks). It preserves text and function-call IDs while
+removing provider item IDs and observational metadata. It rejects non-text,
+opaque reasoning/refusal, malformed calls and duplicate IDs. Keep the original
+message separately for usage information. Do not save failed/partial turns as
+history. The helper does not store history, execute tools or enforce loop limits.
+
+Set explicit tool-call limits, timeouts, cancellation and history bounds in your
+app. Standard LangChain `withStructuredOutput(..., {method:'jsonSchema', strict:true})`
+is available when the gateway route/model supports the schema.
+
+## Example and evidence
+
+The repository's `Examples/LatchwayChat` demonstrates Firebase login, a bounded
+streaming weather-tool loop, ephemeral chat, direct fetch, Stop and diagnostics.
+It consumes npm packages. Its verification report distinguishes physical iOS
+evidence from Android build-only evidence. Request framework attribution remains
+native-owned `react-native-fetch`, including when called through LangChain.
+
+References: [Metro exports](https://metrobundler.dev/docs/package-exports/),
+[Babel assumptions](https://babeljs.io/docs/assumptions#noclasscalls),
+[LangChain ChatOpenAI](https://docs.langchain.com/oss/javascript/integrations/chat/openai).

package/docs/native-installation.md

@@ -0,0 +1,172 @@
+# Native installation
+
+## iOS
+
+Configure `apple.rootKeychainAccessGroup` with the fully resolved private app-ID
+group that appears first in the signed root target. List every explicit
+extension-shared group in `apple.legacySharedKeychainAccessGroups`; the native
+SDK scans only exact root-record coordinates in those groups. Missing,
+wildcard, duplicate, or root-equal groups fail closed, and stale root records
+require an explicit migration.
+
+The podspec pins `Latchway/AppAttest` 1.0.0 and React Native codegen dependencies. Run CocoaPods from the host application after installing the npm package. Enable App Attest for the application identifier and use a real device for conformance; simulators report attestation unsupported.
+
+The Firebase Authentication example pins React Native Firebase 25.1.0 and
+Firebase Apple SDK 12.15.0 and uses CocoaPods static frameworks. The Latchway
+package itself does not depend on Firebase. Firebase has announced that the
+existing CocoaPods releases remain installable but new Firebase Apple SDK
+versions stop shipping through CocoaPods after October 2026; migrate the
+example to the compatible React Native Firebase SPM path only after its pinned
+RN 0.82 native host build is green.
+
+For a source-development run on a physical iPhone or iPad, the example offers a
+separate opt-in Debug bootstrap. `scripts/copy-development-firebase-ios-config.sh`
+validates an external, bundle-matched Firebase plist and copies it only into a
+Debug `iphoneos` build; `scripts/run-development-react-native-ios.sh` keeps the
+custom token and digest out of an allowlisted Xcode build environment, validates
+the complete non-secret deployment coordinates, rechecks grant freshness, and
+force-bundles the exact JavaScript checkout before handing the grant to one
+no-debugger launch. The physical-device run therefore does not require Metro or
+Local Network access, although iOS can still show React Native's one-time Debug
+permission sheet on the first install. Later runs update the existing app so
+that OS consent persists. The app signs in with a new grant, revokes the old
+descriptor-bound family, verifies the root Responses/quota/diagnostics path,
+and prepares the App Intent descriptor. After the one-use grant has been
+destroyed, the root publishes a nonsecret exact-run shared-Keychain challenge
+immediately before the waiting marker. The separately launched Debug App Intent
+captures that challenge before constructing its client, refreshes an
+independently keyed delegated session, and fully consumes one successful bounded
+Responses body. It rechecks the challenge immediately before echoing the run in
+a bounded shared-Keychain receipt. The containing app accepts only its
+native-captured exact run, deletes both artifacts, retires that exact
+descriptor-bound family, and signs out. The runner passes only after retrieving
+the exact random-run
+marker written after terminal cleanup. Its bounded post-wait abort path also
+relaunches the containing app to finish and verify family retirement/sign-out
+after interruption or timeout, deleting both challenge and receipt. The Debug
+native module and marker writer are
+absent from Release. This path verifies local integration only and cannot
+satisfy the protected physical-evidence gate. See the example README for the
+exact runner workflow and possible Shortcuts tap.
+
+Firebase Authentication and Firebase App Check are distinct. The checked-in
+example pins Firebase App/Auth but does not install the native App Check module,
+and a Firebase web App Check registration does not apply to an iOS application.
+When App Check enforcement is enabled for the Firebase resource, pin a
+compatible React Native Firebase App Check dependency and activate the Apple
+App Attest provider before the Auth exchange. A debug App Check provider/token
+is never acceptable in a protected Release candidate.
+
+A production App Attest run requires all of the following, none of which can be
+substituted by a simulator build:
+
+- an App Attest-capable physical iPhone or iPad;
+- a registered App ID with the App Attest capability, a matching Team ID and
+  bundle ID, and a provisioning profile containing the entitlement;
+- `development` or `production` selected consistently in the entitlement,
+  React Native client configuration, gateway application record, and Apple
+  verification policy; and
+- a real application identity token plus the exact gateway/core release named
+  by the synchronized contract lock.
+
+The root-application bridge constructs the App Attest provider with the exact
+`rootKeychainAccessGroup`, `legacySharedKeychainAccessGroups`, and
+`.reactNativeIOS` runtime, then passes the same groups to
+`LatchwayConfiguration`. Keychain, Secure Enclave, session, and accepted App
+Attest key state are runtime-isolated. An extension bridge constructs no App
+Attest provider: iOS app extensions cannot call
+`DCAppAttestService.generateKey`, so extension sessions remain independently
+keyed and delegated from the already attested root application.
+
+The checked-in App Intents target has two intentionally different build
+boundaries. In Debug, its own CocoaPods target links `Latchway/AppExtensions`
+and the native Swift intent performs the local delegated-request proof without
+hosting a React Native JavaScript runtime. In Release, that dependency is not
+linked, no executable Latchway client path is compiled, and the archive/signing
+fixture's intent fails closed. The CocoaPods subspec is imported through module
+`Latchway`, not the SwiftPM-only module name.
+
+Candidate production requires a distinct child bundle ID and provisioning
+profile. The signed root target lists its private app-ID Keychain group first
+and the shared component group second; the first position keeps implicit root
+Keychain writes private. The signed extension lists only the shared group and
+therefore cannot read root-private key, credential, identity, or session state.
+Each provisioning profile must authorize every group its target signs, either
+exactly or with a well-formed terminal wildcard. The extension must not carry
+App Attest. The Debug intent constructs its delegated client with
+`.reactNativeIOS`; the gateway component definition must therefore use platform
+`react_native_ios`, kind `app_intent_extension`, delegated-only trust, and the
+same requested feature as the descriptor prepared by the root.
+
+The root JavaScript API owns the descriptor lifecycle:
+
+- `prepareComponents` provisions one or more exact descriptors;
+- `replaceComponent` rotates/replaces one exact descriptor;
+- root-side `componentDiagnostics` reads redacted local state without acquiring
+  application identity;
+- `revokeComponent` retires one descriptor; and
+- no-argument `revokeCurrentInstallationFamily()` retires the root plus every
+  component in the native iOS SDK's durable root-private descriptor registry;
+  the optional descriptor list additionally covers pre-registry legacy state.
+
+Descriptors are normalized and snapshotted before asynchronous identity work.
+The native SDK registers only their public Keychain coordinates before it can
+create component-local state. Successful cleanup removes a coordinate, while a
+failed Keychain erasure keeps it durable for retry after a later app launch.
+Preparation, replacement, and returned diagnostics are checked against that
+same snapshot, and serialized multi-component input larger than 65,536 bytes is
+rejected in JavaScript before crossing the native bridge. Component keys,
+grants, delegated sessions, and the root identity never cross into JavaScript.
+
+For local native SDK work, declare the sibling `Latchway.podspec` by path in the
+appropriate host targets. The root path declaration lets the autolinked React
+Native pod resolve its App Attest dependency from that source, while the
+extension subspec is Debug-only:
+
+```ruby
+target "ContainingApp" do
+  pod "Latchway", :path => "../../../latchway-ios-sdk"
+  # use_native_modules! / use_react_native! follows here.
+end
+
+target "AppIntents" do
+  pod "Latchway/AppExtensions", :path => "../../../latchway-ios-sdk",
+      :configurations => ["Debug"]
+end
+```
+
+Local paths belong only in the host Podfile. They are absent from the published React Native podspec.
+
+## Android
+
+The library pins the native 1.0.0 Maven coordinates. Those AARs publish Kotlin
+2.3 metadata and require compile SDK 37; the React Native 0.82 host therefore
+pins Kotlin 2.3.21 while retaining RN's supported consumer AGP 8.12 baseline.
+Play Integrity requires the decimal Google Cloud project number in
+`android.playIntegrityCloudProjectNumber`; JavaScript never receives or
+supplies the resulting integrity token.
+
+A production Play Integrity run requires a physical device and a build whose
+package name and signing-certificate digest match the gateway application
+record. Configure the Play Integrity API and its decimal Google Cloud project
+number, upload the signed build to a Play internal/closed/production track, and
+install it from Google Play. A locally sideloaded debug APK can prove compilation
+and bridge behavior, but it is not production Play Integrity evidence. Exercise
+both hardware-backed/StrongBox-available and fallback policy variants on the
+device matrix required by the deployment.
+
+For local native SDK work, publish the native artifacts to a disposable Maven repository and set one of:
+
+```sh
+./android/gradlew -p android -PlatchwayNativeRepository=/absolute/path/to/maven check
+```
+
+```sh
+LATCHWAY_NATIVE_REPOSITORY=/absolute/path/to/maven ./android/gradlew -p android check
+```
+
+The repository is content-filtered to `dev.latchway`. Composite-build substitution is intentionally avoided because the Android SDK and React Native 0.82 currently use incompatible Gradle major versions.
+
+## Release dependency check
+
+CI must run once against only the published CocoaPods/Maven coordinates, without local path or repository overrides, before npm publication. A local native build proving source compatibility does not replace that consumer check. The manual `Published dependency consumer` workflow performs that gate; the promotion-dispatched release workflow repeats it before npm publication.