@aotui/mobile-ai-native 0.1.0-alpha.0 → 0.1.0-alpha.1

package/GUIDE.md

@@ -1,11 +1,16 @@
 # GUIDE: Building an Agent Native iOS Calendar App
 
-This guide is for a developer who wants to build a high-quality Agent Native calendar app on iOS using `@aotui/mobile-ai-native`.
+This guide is for a developer who wants to build a high-quality agent-native calendar app on iOS using `@aotui/mobile-ai-native`.
+
+Important boundary:
+
+- `@aotui/mobile-ai-native` is the runtime core
+- `@aotui/mobile-ai-native-react-native` is the React Native / Expo host adapter
 
 The goal is simple:
 
 - humans use a normal GUI calendar
-- the LLM uses tools through a TUI snapshot
+- the LLM uses tools through a snapshot
 - both operate on the same app state
 - the human can see the result of the LLM's actions
 
@@ -31,9 +36,26 @@ They must meet in the same place:
 
 That is the whole trick.
 
-## 2. Why This Architecture Matters
+## 2. How The Snapshot Works
+
+The LLM should not guess ids from pixels.
+It should read the current `SnapshotBundle`.
+
+In the current runtime, the snapshot is assembled from ordered `<View>` fragments:
+
+- the first fragment is the static root navigation fragment with `type: "Root"`
+- later fragments are mounted business views derived from current state
+- `markup` is the composed xml+markdown snapshot
+- `views` preserves the fragment order
+- `refIndex` resolves semantic refs by exact key lookup
+- `visibleTools` is the tool list for that same render tick
 
-If the LLM drives the GUI by fake taps, your system becomes fragile.
+`snapshotId` is non-negotiable.
+If the app changes after the LLM reads a snapshot, the tool call must still be tied to the exact snapshot the model saw.
+
+## 3. Why This Architecture Matters
+
+If the LLM drives the GUI by fake taps, the system becomes fragile.
 
 Why?
 
@@ -50,30 +72,31 @@ Instead, this framework makes the LLM act on meaning:
 - `changeCalendarView`
 
 The GUI is one projection of state.
-The TUI snapshot is another projection of state.
+The snapshot is another projection of state.
 
-The LLM should never guess ids from the screen.
+The LLM should never infer refs from the visual layout.
 It should receive semantic refs from the current `SnapshotBundle`.
 
-## 3. The Core Mental Model
+## 4. The Core Mental Model
 
 Your calendar app should follow this loop:
 
 `State -> GUI`
-`State -> TUI Snapshot`
+`State -> Root view + mounted business views -> SnapshotBundle`
 `Tool -> Action -> Event/Effect -> State`
 `GUI Event -> Action -> Event/Effect -> State`
 
 That means:
 
 - GUI controls do not own business logic
-- TUI does not own business logic
+- snapshot views do not own business logic
 - tools do not own business logic
 - `Action` is the one real business entry
+- effects are framework-managed side effects, but the app still owns what they mean
 
-## 4. Calendar App State
+## 5. Calendar App State
 
-A good Agent Native calendar app should have state shaped more like this:
+A good agent-native calendar app should have state shaped more like this:
 
 ```ts
 type CalendarState = {
@@ -95,26 +118,26 @@ Good rule:
 
 - if it affects GUI, TUI, tool visibility, or trace, it belongs in framework state
 - if it is only a tiny render helper, keep it local
+- if it must be read by the host through a selector, keep it in the runtime store so `useRuntimeState()` can subscribe to it
 
-## 5. Calendar Actions
+## 6. Calendar Views And Tools
 
-Your first calendar app should expose a very small action set:
+Model the app as a static root plus mounted runtime views:
 
-- `openEvent`
-- `searchEvents`
-- `createEvent`
-- `moveEvent`
-- `changeCalendarView`
+- `RootView` is the navigation map, currently emitted with `type: "Root"`
+- `CalendarView` can be always mounted when the calendar shell is active
+- `EventDetailView` can mount only when an event is selected
+- `SearchResultView` can mount only while search results are present
 
-Start smaller than you want.
-You can always add more later.
+The tool surface should follow the same semantic grouping.
 
-The important rule is:
+- register tools against a `viewType`
+- filter them with `visibility(state)`
+- only expose tools for currently relevant view types
 
-- actions should be domain actions
-- not UI actions like `tapButton` or `scrollList`
+That keeps the calendar agent surface aligned with the current screen reality without pretending the runtime is a desktop tree inspector.
 
-## 6. Why Refs Matter in Calendar Apps
+## 7. Why Refs Matter In Calendar Apps
 
 Calendars are full of structured data:
 
@@ -153,7 +176,7 @@ const [eventsRef, eventRef] = useArrayRef("event", visibleEvents, "events");
 ))}
 ```
 
-## 7. Why `snapshotId` Is Non-Negotiable
+## 8. Why `snapshotId` Is Non-Negotiable
 
 The screen can change after the LLM reads it.
 
@@ -169,15 +192,11 @@ So tool execution must always be tied to the exact snapshot the LLM saw:
 await bridge.executeTool("openEvent", { event: "events[0]" }, snapshotId);
 ```
 
-This prevents the runtime from guessing against the latest UI.
-
-That is a big deal.
-It is the difference between:
+That prevents the runtime from guessing against the latest UI.
 
-- a reliable system
-- and a haunted house
+In the hardened runtime, the snapshot registry distinguishes `SNAPSHOT_NOT_FOUND` from `SNAPSHOT_STALE`. A tool execution that mutates state marks its originating snapshot stale, even if the action returns a recoverable failure result. That forces the next reasoning turn to fetch a fresh snapshot.
 
-## 8. How To Build the iOS App
+## 9. How To Build The iOS App
 
 ### Step 1: Keep this package as the core
 
@@ -196,15 +215,18 @@ The React Native app should do only host work:
 - host the agent session
 - ask the framework for `SnapshotBundle`
 - pass tool calls into `executeTool`
+- subscribe to state and trace through the runtime hooks instead of copying framework state into local component state
 
-### Step 3: Build GUI and TUI as separate projections
+In practice, that means mounting the core through `createReactNativeAppRuntime()` and `AppRuntimeProvider` from `@aotui/mobile-ai-native-react-native`.
 
-Do not auto-generate TUI from GUI.
+### Step 3: Build GUI and snapshot views as separate projections
+
+Do not auto-generate the snapshot from GUI.
 
 For calendar apps this is especially important because:
 
 - GUI cares about touch and spatial layout
-- TUI cares about semantic clarity for the model
+- snapshot views care about semantic clarity for the model
 
 ### Step 4: Start with one vertical slice
 
@@ -223,20 +245,30 @@ Only after that is stable, add:
 - move
 - delete
 - recurring events
+- trace UI for recent AI actions
 
-## 9. Suggested First Calendar TUI
+## 10. Suggested First Calendar Snapshot
 
-Your first TUI should be boring and clear, not clever:
+Your first snapshot should be boring and clear, not clever:
 
 ```tsx
-<screen name="Calendar">
+<View id="root" type="Root" name="Navigation">
+  ## Calendar Navigation
+  - Root
+    - purpose: app navigation and view map
+  - Calendar
+    - enter: mounted by default after launch
+    - actions: open_event, search_events, change_calendar_view
+  - EventDetail
+    - enter: use open_event from Calendar
+    - actions: update_event, close_event
+</View>
+
+<View id="calendar" type="Calendar" name="Week Calendar">
   <text>View: week</text>
   <text>Date: 2026-03-24</text>
   <text>{daysRef("Visible days")}</text>
-  {events.map((event, index) => (
-    <item key={event.id}>{eventRef(index, `${event.title} at ${event.startTime}`)}</item>
-  ))}
-</screen>
+</View>
 ```
 
 The LLM does not need visual beauty.
@@ -246,72 +278,10 @@ It needs:
 - meaningful refs
 - clear tool choices
 
-## 10. Quality Bar for a Good Agent Native Calendar App
-
-Before you call the app "good", verify these:
-
-### State correctness
-
-- GUI and TUI always reflect the same event state
-- tool calls only act on snapshot-scoped refs
-
-### Tool correctness
-
-- invisible tools are not callable
-- stale `snapshotId` fails cleanly
-- missing refs fail with explicit errors
-
-### UX correctness
-
-- human sees the result of AI actions
-- recent AI action summary is visible
-- event openings, searches, and edits are understandable
-
-### Product correctness
-
-- no tool is named after a button
-- tools match domain intent
-- TUI exposes enough semantic data without dumping noise
-
-## 11. What This Package Does Not Give You Yet
-
-Be honest with yourself:
-
-this package is still an alpha core.
-
-It does not yet give you:
-
-- a full React Native adapter
-- iOS simulator harness
-- production persistence
-- production networking
-- voice or background agent integration
-
-That is okay.
-
-It gives you the hardest part first:
-
-- the protocol spine
-
-## 12. Recommended Build Order
-
-If your friend is building the calendar app, this is the order I recommend:
-
-1. build one RN screen shell
-2. integrate framework state and tool bridge
-3. implement week view with event refs
-4. implement `openEvent`
-5. implement `searchEvents`
-6. add trace banner for recent AI action
-7. add create/edit flows
-8. only then add advanced calendar features
-
-## 13. The One Sentence To Remember
-
-An Agent Native iOS app is not:
-
-- "AI controlling UI"
+## 11. Quality Bar For A Good Agent Native Calendar App
 
-It is:
+A good app should feel like one system, not two loosely related interfaces.
 
-- "one app where GUI and LLM share the same domain actions and the same state"
+If the GUI and snapshot disagree, the user will feel it immediately.
+If tools are visible in the wrong view type, the agent will feel it immediately.
+If refs drift from the current render tick, both paths become unreliable.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Johnny Zhang
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,21 +1,93 @@
 # @aotui/mobile-ai-native
 
-This package is an alpha host-agnostic core for building Agent Native mobile apps.
+This package is the hardened runtime core for building agent-native mobile apps.
 
-It currently proves the smallest end-to-end loop of the framework:
+It is the **core**, not the full React Native host layer.
+React Native / Expo mounting now lives in [`@aotui/mobile-ai-native-react-native`](../packages/mobile-ai-native-react-native/README.md).
 
-`State -> SnapshotBundle -> Tool Call(ref_id + snapshotId) -> Action -> Event/Effect -> State -> GUI/TUI refresh`
+It provides the state store, action runtime, trace lifecycle, snapshot registry, and tool bridge needed for a real mobile host.
 
-If you want a practical build guide for a real iOS app, read [GUIDE.md](./GUIDE.md).
+The current snapshot model is view-based:
+
+`State -> static Root view + state-derived mounted views -> SnapshotBundle -> Tool Call(ref_id + snapshotId) -> Action -> Event/Effect -> State -> GUI/TUI refresh`
 
 ## What This Slice Proves
 
 - one shared state system drives both GUI and TUI
-- TUI is handwritten and can expose semantic refs with `useDataRef` and `useArrayRef`
+- the root view is static navigation knowledge, not runtime state
+- business views are mounted from current state and represent runtime reality
+- tools are scoped by `viewType` and then filtered by `visibility(state)`
 - the framework builds one atomic `SnapshotBundle`
+- snapshot markup is composed from ordered `<View>` fragments
 - tools execute against the exact `snapshotId` the LLM saw
 - `refIndex` stores serializable snapshot payloads, not live object references
-- one pure local action and one effect-driven action both work
+- mutated tool results stale the originating snapshot, even when the result is recoverable
+- trace entries record the action lifecycle: `started`, `updated`, `succeeded`, and `failed`
+
+## SnapshotBundle
+
+The LLM-facing read model is:
+
+```ts
+type SnapshotBundle = {
+  snapshotId: string;
+  generatedAt: number;
+  markup: string;
+  views: readonly ViewFragment[];
+  tui: string;
+  refIndex: Record<string, RefIndexEntry>;
+  visibleTools: readonly ToolDefinition[];
+};
+```
+
+Current behavior to keep in mind:
+
+- `markup` is the composed xml+markdown snapshot built from ordered `<View>` fragments
+- `views` preserves the ordered fragment list, with the `Root` fragment first
+- `tui` is retained as a compatibility readout and may differ from `markup`, but it should be produced from the same snapshot generation pass
+- `refIndex` and `visibleTools` are produced and frozen alongside snapshot creation
+
+The bundle is intended to be atomic:
+
+- `markup`
+- `views`
+- `tui`
+- `refIndex`
+- `visibleTools`
+
+Today the runtime hard-validates `markup` against `views`, then freezes the associated `tui`, `refIndex`, and `visibleTools` outputs generated on that same snapshot path.
+
+## RootView And Mounted Views
+
+`RootView` is the conceptual navigation role, and the current runtime emits it as a fragment with `type: "Root"`.
+
+It explains:
+
+- what view types exist
+- how to enter them
+- what each view type is for
+
+It does not try to narrate runtime state.
+
+Mounted business views are the runtime reality.
+
+They are derived from current state and describe:
+
+- which concrete views are mounted right now
+- what state each mounted view is showing
+- what refs and actions are relevant in that state
+
+That means the LLM should read the static root first, then read the mounted business views for the live app state.
+
+## Tool Model
+
+Tools are defined against a semantic `viewType`, then filtered by current state.
+
+That gives the runtime this rule:
+
+`visibleTools = tools for currently relevant viewTypes + visibility(state)`
+
+So a tool can exist in the app, be mounted to a view type, and still be hidden when the current state does not allow it.
 
 ## Core Contract
 
@@ -32,7 +104,20 @@ Then it calls a tool with:
 await bridge.executeTool("openMessage", { message: "messages[0]" }, snapshotId);
 ```
 
-The runtime resolves that `ref_id` from the `SnapshotBundle.refIndex` for the same `snapshotId`.
+For tools that declare `meta.supportsRefs === true`, the bridge resolves top-level string inputs as either exact `ref_id` values or canonical marker strings from that snapshot's `refIndex`.
+It does not infer nested field refs or field-level ref metadata.
+
+The low-level React-family host path inside the core is still present because the adapter composes it, but product code should prefer the dedicated RN adapter package.
+
+The adapter-facing runtime path is:
+
+- `createReactAppRuntime()` owns the store, action runtime, snapshot registry, trace store, and tool bridge
+- `AppRuntimeProvider` publishes that runtime through context
+- `useRuntimeState(selector)` subscribes to store updates with `useSyncExternalStore`
+- `useRuntimeTrace(selector)` subscribes to the trace store the same way
+- `createReactNativeAppRuntime()` in the adapter package wraps that core runtime and exposes `runtime.ai.getSnapshot()` / `runtime.ai.executeTool(...)` for host-safe tool execution
+
+That means GUI consumers react to state and trace changes without pulling the whole runtime object into component state.
 
 ## Ref APIs
 
@@ -55,51 +140,22 @@ const [listRef, itemRef] = useArrayRef("message", messages, "messages");
 <item>{itemRef(0, "Welcome back")}</item>;
 ```
 
-## SnapshotBundle
-
-The LLM-facing read model is:
-
-```ts
-type SnapshotBundle = {
-  snapshotId: string;
-  generatedAt: number;
-  tui: string;
-  refIndex: Record<string, { type: string; value: unknown }>;
-  visibleTools: ToolDefinition[];
-};
-```
-
-This is intentionally atomic:
-
-- `tui`
-- `visibleTools`
-- `refIndex`
-
-must all come from the same render tick.
-
-## Why `refIndex` Stores Serializable Payloads
-
-Screens can change after the LLM reads them.
-Live object references may already be gone.
-
-So `refIndex` stores serializable snapshot payloads.
-When the LLM later calls a tool, the framework reconstructs the action input from the payload attached to that `snapshotId`.
-
 ## Current Status
 
-This is not yet a full React Native runtime or iOS shell.
+This package is the core, not the full app shell.
 
 What it gives you today:
 
 - shared state core
 - semantic refs with `useDataRef` and `useArrayRef`
 - atomic `SnapshotBundle`
+- static root navigation plus state-derived mounted business views
 - snapshot-scoped tool execution
-- a working inbox vertical slice
+- a pure core that can now be mounted by the dedicated RN / Expo adapter
+- structured trace and effect contracts
 
 What you still need for a production iOS app:
 
-- a thin React Native host adapter
 - real GUI components
 - model orchestration and networking
 - product-level trace UI and persistence
@@ -112,3 +168,13 @@ The inbox demo exposes:
 - `searchMessages`
 
 and proves that GUI and TUI both refresh from the same state after tool execution.
+
+## Runtime Boundaries
+
+Keep the framework and app responsibilities separated:
+
+- framework owns the store, action runtime, snapshot registry, trace runtime, tool bridge, and host adapter
+- business apps own state shape, domain actions, handwritten TUI, and app-specific effect behavior
+- actions can read state, emit events, run effects, and update trace summaries
+- effects can read state, emit events, and report structured success or failure, but they do not write state directly
+- snapshot coherence is enforced for the textual view representation, so `markup`, `views`, and `tui` must agree for the same render tick; `refIndex` and `visibleTools` are built and frozen alongside that snapshot path but are not yet cross-validated field-by-field