# @lssm-tech/app.personalos-mobile

Premium Expo Router iOS and Android shell for PersonalOS.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `0.2.5`
- Package path: `packages/apps/personalos-mobile`
- Manifest path: `packages/apps/personalos-mobile/package.json`
- Manifest Git blob: `9ca57398f4fd662de1767f092d91da360716ec67`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/app.personalos-mobile](https://lssm.co/docs/packages/app.personalos-mobile/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-mobile)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-mobile/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-mobile/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.personalos-mobile.txt)

## Package metadata

```json
{
  "layer": "apps",
  "physicalArea": null,
  "primaryArea": "personal-and-learning",
  "classification": {
    "privateDeclared": true,
    "catalogFamily": null,
    "catalogKind": null,
    "catalogStatus": null,
    "adoptionMode": null,
    "stability": null
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: true — workspace only.

Primary area: [Personal workflows, learning and progress](https://lssm.co/docs/areas/personal-and-learning/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/apps/personalos-mobile/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-mobile/README.md",
  "blobSha": "14af2135554c3da17015f7fd6abe2adf66ebb61c",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# PersonalOS Mobile

Premium Expo Router shell for the PersonalOS golden journey on iOS and Android. It composes `@lssm-tech/module.personal-experience` with the goals, productivity, household, and health module view-model seams.

The mounted shell now loads the authenticated subject-bound experience and
workspace projections from the canonical PersonalOS API. Guided native forms
build schema-validated, domain-separated commands for the complete golden
journey instead of presenting inert affordances. Server denial and revision
conflicts fail closed; accepted commands refresh the authoritative projection.
The shell consumes the integrity-bound `presentation` member of that projection
for exact area, component, and `<area>.manage` boundaries. Missing or malformed
presentation metadata, plus resolutions older than five minutes, are discarded
so safe display-only state remains usable, while every governed action fails
closed until a current bound presentation permits it. Presentation preferences change only density, detail,
guidance, control explanation, media feedback, pace, and narrative display; they
cannot grant authority and can be reset or restored without clearing form drafts.
Household invitation, activation, delegation, and revocation use the shared
runtime draft constructor before Expo Crypto performs the native
domain-separated SHA-256 binding. Mobile does not redefine their risk,
authority, offline eligibility, or excluded-action policy.
The embedding native host registers its AuthOS login/deep-link exchange through
`registerPersonalOsNativeAuthBootstrap`; the returned opaque session enters the
device-only vault before projection loading. A clean standalone install without
that host seam stays signed out and fails closed—no development token or public
environment secret is accepted.
For isolated simulator qualification, Metro resolves an ephemeral AuthOS
bootstrap only when `PERSONAL_OS_MOBILE_E2E_AUTH=enabled`; the bootstrap
exchanges a run-specific nonce with the loopback API host. Normal production
exports resolve a no-op module instead, and the export command scans both Hermes
bundles for the route, header, token, and E2E error sentinels before succeeding.

The native runtime is pinned to the Expo 57-compatible React Native 0.86 line.
SecureStore identifiers use only Expo-supported letters, numbers, periods,
hyphens, and underscores, so both opaque sessions and SQLCipher keys survive the
real native boundary instead of failing only after installation.

## Product surfaces

- Today: capacity-aware plan, check-in, and missed-day recovery.
- Goals: personal mission, observable goals, minimized outcome measurements,
  and online-authorized record/correct/remove controls that preserve history.
- Health: accessible, non-clinical category history with minimized status,
  observation/quarantine counts, and latest source timestamp plus native
  HealthKit/Health Connect host ports; raw measurements and provider payloads
  never enter the view contract.
  A separate native summary renders the optional exact-subject wellbeing-goal
  window with localized safe metric, lifecycle, direction, observation count,
  and uncertainty-aware outcome plus explicit non-causal/non-medical copy.
- Household: membership plus explicit, expiring, revocable support, including
  one-goal proposal-only grants and immediate revoke, block, and categorical
  report controls.
- Privacy: minimized purpose/downstream-consumer/expiry/status consent dashboard,
  fixed one-year PersonalOS planning grant, active-grant revocation, coach
  explanation/undo, and online-only rights operations. Consent controls use
  the shared lifecycle schema and never enter the offline outbox.
- Review: progress and wellbeing reflection without medical or causal claims.

The shared Personal Calm design pack drives comfortable density, calm motion, platform-native navigation, progressive disclosure, 44-point touch targets, and light/dark readiness. Copy is typed in English, French, and Spanish; layout direction is derived independently so RTL locales can be added without restructuring screens.

## Trust boundaries

- Session tokens use device-only `expo-secure-store` custody.
- The last authenticated subject marker uses the same device-only custody. An
  offline process relaunch can load only that subject's exact encrypted
  experience/workspace pair; foreign subjects, mismatched revisions, missing
  rows, and malformed projections fail closed.
- Local projections use SQLCipher. A 256-bit random key is generated by `expo-crypto`, stored in device-only secure storage, and applied before schema access.
- Projection payload policy rejects tokens, credentials, secrets, and raw provider payload keys.
- Only commands in the shared exact-action registry can enter the encrypted offline outbox. Caller-provided risk or undo metadata is never authoritative.
- Presentation `allowed`, conditional, approval, blocked, and hidden boundaries
  are enforced before canonical command construction and again at the
  authenticated session boundary. Preferences never widen those boundaries.
- Conditional and approval-required actions remain disabled until an exact
  condition or approval artifact and submission route exist; they cannot fall
  through to direct governed-command dispatch or offline queuing.
- Missing or invalid presentation metadata leaves generic display state usable
  but blocks all governed actions. Sensitive and high-risk actions always
  require current online authority, regardless of presentation preferences.
- Form drafts live above pending, denial, and conflict screen transitions.
  Hidden or blocked actions suppress their controls without deleting drafts,
  and reduced-motion mode removes modal slide animation. Draft storage is bound
  to the exact subject and actor refs and clears synchronously on sign-out or
  identity change, preventing a person's or delegate's draft from appearing in
  another authority context.
- The mounted session also observes the server-issued opaque tenant/consent
  binding. Exact subject, actor, tenant, and consent changes discard retiring
  Personalization buffers before the next scope can collect; transient
  checking, denial, offline, and error states preserve the current scope.
  Buffer attachment is unavailable without granted consent.
- The outbox validates the complete PersonalOS command envelope, authenticated subject, expected revision, canonical payload SHA-256 digest, and registry-owned undo command before its SQLCipher write.
- Canonical command binding uses the `@lssm-tech/lib.personal-os-runtime/digest-port`
  lane (runtime domain map and canonical JSON) with an expo-crypto SHA-256
  adapter, so every shared workspace domain is mapped exactly as on the server,
  including private `progress_celebration` and high-risk `guardrails` domains.
  Both remain online-only and are not exposed as offline or silently
  authoritative actions.
- Replay runs the owner `@lssm-tech/module.personal-experience/offline-replay`
  state machine (25 commands per pass, 5 attempts, backoff, policy re-check). It reconstructs and validates the exact
  workspace command from the trusted registry, authenticated subject,
  revision, envelope, idempotency key, and domain-separated payload digest,
  then submits it to the canonical `/v1/domain-commands` authority boundary.
  Server denial and revision conflict remain blocked for recovery; transient
  failures use bounded retry and preserve order.
- Concurrent reconnect/session refresh triggers share one in-flight load and
  one replay pass, preventing duplicate transport attempts before server
  idempotency is needed.
- Version-one outbox rows are retained but marked `legacy_envelope_missing` because they cannot be proven safe to replay.
- Consent, sharing, native health connections, delegation, authority, export, and deletion revalidate online.
- HealthKit and Health Connect are real host ports, not mocked production adapters. Unavailable or denied native authorization fails closed.

## Commands

```bash
bun run lint:check
bun run typecheck
bun run test
bun run build
bun run ios
bun run android
```


Maestro definitions live in `tests-mobile/flows`. On 2026-08-13, bounded
flows passed on an iPhone 16 Pro simulator running iOS 18.5: clean-install
AuthOS denial; an ephemeral loopback AuthOS exchange followed by authenticated
navigation across all six tabs and every canonical golden-journey action entry;
the authenticated missed-day recovery form; and a source-bound native mutation
run that durably created the household, mission, and first active goal through
the production-composition API. These runs qualify native startup, navigation,
guided-form reachability, and that exact revision-three mutation foundation.
An additional iPhone 16 Pro simulator sequence established an authoritative
workspace, disconnected the app from the preserved authority server, relaunched
the app from an encrypted subject-bound projection pair, queued one reversible
check-in, restored connectivity to that same server, and
committed exactly one replay at expected revision 2. The server advanced to
revision 3 with one minimized check-in and zero pending low-risk commands.
These runs do not prove the remaining mutation journey, broader
denial/recovery, Android, assistive technology, a real device, production AuthOS,
provider accounts, store signing, or a canary and must not be counted as
`live_verified` evidence.

The earlier navigation and recovery replay remains a historical artifact, but
later mobile source changes invalidate its current source binding. The current
matrix therefore credits only the newer source-bound mutation run until those
broader flows are rerun on the latest source commit.

ContractSpec Connect was unavailable to this lane. The release capsule records
the resulting review gap; it is not treated as approval evidence. The remaining
native mutation and broader denial/recovery journeys, Android simulator,
VoiceOver, TalkBack,
real-device, provider-account, store-signing, deployed-host, and canary evidence
remain pending and are not inferred from local tests or native bundle exports.

Maintainers can replay a current-source iOS simulator flow with the manually
dispatched `PersonalOS Native Qualification` GitHub Actions workflow. The job
creates an isolated simulator, builds the current Expo development client,
starts the real PersonalOS E2E API and Metro hosts with a run-specific masked
nonce, runs the selected Maestro flow, validates the authoritative workspace,
and retains JUnit plus minimized test-state diagnostics for 14 days. A workflow
run is qualification evidence only after its exact commit, result, artifact
digest, simulator/runtime, and observed time are recorded in the PersonalOS
source-bound qualification ledger.


## Declared capabilities

This manifest does not declare a capability catalogue. Assess the package using its guide, import map and source.

## Catalogue metadata

```json
{
  "visualTesting": {
    "status": "platform-qualified",
    "platform": "native",
    "owner": "@contractspec-core",
    "qualificationCommands": [
      "bun run typecheck",
      "bun run test"
    ],
    "evidenceManifest": "./storybook-platform-qualification.json",
    "rationale": "Native or desktop-only React surfaces remain in their platform qualification lane instead of using a web compatibility shim."
  }
}
```

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

This workspace does not declare package export paths.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": null,
  "files": null,
  "publishExports": null
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/lib.contracts-spec](https://lssm.co/docs/packages/lib.contracts-spec/): `workspace:*`
- [@lssm-tech/lib.design-catalog](https://lssm.co/docs/packages/lib.design-catalog/): `workspace:*`
- [@lssm-tech/lib.design-system](https://lssm.co/docs/packages/lib.design-system/): `workspace:*`
- [@lssm-tech/lib.personal-health-runtime](https://lssm.co/docs/packages/lib.personal-health-runtime/): `workspace:*`
- [@lssm-tech/lib.personal-health-spec](https://lssm.co/docs/packages/lib.personal-health-spec/): `workspace:*`
- [@lssm-tech/lib.personal-os-runtime](https://lssm.co/docs/packages/lib.personal-os-runtime/): `workspace:^`
- [@lssm-tech/lib.personal-os-spec](https://lssm.co/docs/packages/lib.personal-os-spec/): `workspace:*`
- [@lssm-tech/lib.presentation-runtime-core](https://lssm.co/docs/packages/lib.presentation-runtime-core/): `workspace:*`
- [@lssm-tech/lib.ui-kit](https://lssm.co/docs/packages/lib.ui-kit/): `workspace:*`
- [@lssm-tech/module.personal-experience](https://lssm.co/docs/packages/module.personal-experience/): `workspace:*`
- [@lssm-tech/module.personal-goals](https://lssm.co/docs/packages/module.personal-goals/): `workspace:*`
- [@lssm-tech/module.personal-health](https://lssm.co/docs/packages/module.personal-health/): `workspace:*`
- [@lssm-tech/module.personal-household](https://lssm.co/docs/packages/module.personal-household/): `workspace:*`
- [@lssm-tech/module.personal-productivity](https://lssm.co/docs/packages/module.personal-productivity/): `workspace:*`
- `expo`: `~57.0.21`
- `expo-crypto`: `~57.0.2`
- `expo-router`: `~57.0.20`
- `expo-secure-store`: `~57.0.3`
- `expo-sqlite`: `~57.0.2`
- `expo-status-bar`: `catalog:native`
- `lucide-react-native`: `catalog:ui`
- `nativewind`: `catalog:native`
- `react`: `catalog:`
- `react-native`: `0.86.2`
- `react-native-css`: `catalog:native`
- `react-native-safe-area-context`: `catalog:native`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `@tailwindcss/postcss`: `^4.3.3`
- `@types/bun`: `catalog:types`
- `@types/react`: `catalog:native`
- `happy-dom`: `catalog:testing`
- `postcss`: `catalog:build`
- `postcss-load-config`: `^6.0.1`
- `tailwindcss`: `catalog:build`
- `typescript`: `catalog:native`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "android": "expo run:android",
  "build": "bun scripts/export-native.mjs",
  "deps:check": "expo install --check",
  "dev": "expo start",
  "ios": "expo run:ios",
  "lint": "bun run lint:fix",
  "lint:check": "node ../../../scripts/biome.cjs check .",
  "lint:fix": "node ../../../scripts/biome.cjs check --write .",
  "start": "expo start",
  "test": "bun test",
  "typecheck": "tsgo --noEmit"
}
```

## Declared documentation links

No additional documentation links are declared in the inspected catalogue.

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/app.personalos-mobile.txt",
  "route": "/llms/app.personalos-mobile",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.personalos-mobile.txt",
  "blobSha": "14af2135554c3da17015f7fd6abe2adf66ebb61c",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```