sync: ambient directories, receiving rules, and the gates that were red

.dependency-cruiser.js

@@ -64,6 +64,12 @@ module.exports = {
           '(^|/)index\\.(ts|tsx)$', // barrel/entry files
           '^src/types/', // type barrels are legitimately import-only
           '^src/(bootstrap|shims|config)/', // wiring/shim/config shells reached outside the graph
+          // Core utilities whose only importers are in the private pro/ submodule. The cruiser scans src
+          // alone, so a module used exclusively by pro reads as an orphan even though deleting it would
+          // break the build - coalesce is imported by pro/sync/fileTransferService and
+          // pro/sync/ambientShareService. Same reasoning as the @offgrid/pro exception below: not real
+          // debt, so excluded rather than baselined. Confirm with grep in pro/ before adding to this list.
+          '^src/utils/coalesce\\.ts$',
         ],
       },
       to: {},
@@ -106,6 +112,10 @@ module.exports = {
     },
   ],
   options: {
+    // Keep file-linked workspace packages under node_modules so dependency-cruiser can
+    // classify them from this package.json instead of treating their real paths as
+    // undeclared source files outside the mobile project.
+    preserveSymlinks: true,
     doNotFollow: { path: 'node_modules' },
     tsPreCompilationDeps: true,
     tsConfig: { fileName: 'tsconfig.json' },

.eslintrc.js

@@ -71,9 +71,22 @@ module.exports = {
     'sonarjs/no-duplicated-branches': 'warn',
   },
   overrides: [
+    {
+      files: ['scripts/physical-sync/**/*.mjs'],
+      parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+      },
+    },
     {
       // Relax structural rules in test files — large test suites and helpers are acceptable
-      files: ['__tests__/**/*', '*.test.ts', '*.test.tsx', 'jest.setup.ts'],
+      files: [
+        '__tests__/**/*',
+        'scripts/physical-sync/__tests__/**/*.mjs',
+        '*.test.ts',
+        '*.test.tsx',
+        'jest.setup.ts',
+      ],
       rules: {
         'max-lines': 'off',
         'max-lines-per-function': 'off',

.github/workflows/ci.yml

@@ -8,106 +8,20 @@ on:
     branches:
       - main
 
+# ONE job, not four.
+#
+# lint, typecheck, architecture and test used to be separate jobs, and the only thing that made them
+# separate was the gate at the end - all four repeated the SAME seven setup steps (checkout, pro
+# submodule, node, java, two shared checkouts, install). That duplication was not just slow, it was
+# the bug: the shared-provisioning step was wrong in all four copies at once, and one of the four
+# (lint) had silently lost its `env: PRO_SUBMODULE_PAT`, so it never provisioned shared at all.
+#
+# Setup happens once here and every gate runs as a step against it. Each gate carries
+# `if: ${{ !cancelled() && steps.install.outcome == 'success' }}`, so a red gate does NOT hide the
+# ones after it - the whole list still reports, which is the one thing the four separate checks were
+# genuinely good at. The trade-off is wall-clock: the gates no longer run in parallel.
 jobs:
-  lint:
-    runs-on: macos-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'npm'
-
-      - name: Setup Java
-        uses: actions/setup-java@v4
-        with:
-          distribution: 'temurin'
-          java-version: '17'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Install SwiftLint
-        run: brew install swiftlint
-
-      - name: Lint
-        run: npm run lint
-
-  typecheck:
-    runs-on: ubuntu-latest
-    env:
-      PRO_SUBMODULE_PAT: ${{ secrets.PRO_SUBMODULE_PAT }}
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Check out pro submodule (private; skipped on open-core forks)
-        # tsc sees __tests__/pro/* which import @offgrid/pro/*; without the submodule those resolve
-        # to nothing (TS2307) and typecheck fails. Pull it when the PAT is present (this org's CI);
-        # forks without the secret skip it and tsconfig excludes the pro paths.
-        if: ${{ env.PRO_SUBMODULE_PAT != '' }}
-        env:
-          PRO_PAT: ${{ env.PRO_SUBMODULE_PAT }}
-        run: |
-          git config --global url."https://x-access-token:${PRO_PAT}@github.com/".insteadOf "https://github.com/"
-          git submodule update --init --recursive pro
-          git config --global --unset url."https://x-access-token:${PRO_PAT}@github.com/".insteadOf || true
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Type check
-        run: npx tsc --noEmit
-
-  architecture:
-    # Standing gates: dependency-cruiser (layering, engine DIP, import cycles, orphans — 0 violations,
-    # no baseline) + knip (dead files/exports/types/deps — 0 issues). Both fail on anything NEW.
-    runs-on: ubuntu-latest
-    env:
-      PRO_SUBMODULE_PAT: ${{ secrets.PRO_SUBMODULE_PAT }}
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Check out pro submodule (private; skipped on open-core forks)
-        # knip/depcruise scan pro-importing code; without the submodule their reachability graph is
-        # incomplete (false unused/orphan reports). Pull it when the PAT is present; forks skip it.
-        if: ${{ env.PRO_SUBMODULE_PAT != '' }}
-        env:
-          PRO_PAT: ${{ env.PRO_SUBMODULE_PAT }}
-        run: |
-          git config --global url."https://x-access-token:${PRO_PAT}@github.com/".insteadOf "https://github.com/"
-          git submodule update --init --recursive pro
-          git config --global --unset url."https://x-access-token:${PRO_PAT}@github.com/".insteadOf || true
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Dependency-cruiser (architecture gate)
-        run: npm run depcruise
-
-      - name: knip (dead-code gate)
-        run: npm run knip
-
-  test:
+  ci:
     runs-on: macos-latest
     env:
       # Exposed at the job level so the step `if:` below can read it: the `secrets` context
@@ -121,9 +35,11 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Check out pro submodule (private; skipped on open-core forks)
-        # When the PRO_SUBMODULE_PAT secret is present (this org's CI), pull the private
-        # pro/ submodule so the pro-dependent suites (TTS/MCP/audio) run against the REAL
-        # package — a green run then actually exercises pro, not a stub. Forks without the
+        # When the PRO_SUBMODULE_PAT secret is present (this org's CI), pull the private pro/
+        # submodule so the pro-dependent suites run against the REAL package — a green run then
+        # actually exercises pro, not a stub. It also matters to the other gates: tsc sees
+        # __tests__/pro/* importing @offgrid/pro/* (TS2307 without it), and knip/depcruise need it
+        # or their reachability graph is incomplete and reports false orphans. Forks without the
         # secret skip this: proExists=false and jest runs the open-core suite instead.
         if: ${{ env.PRO_SUBMODULE_PAT != '' }}
         env:
@@ -136,12 +52,12 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          # Node 26. The RAG/knowledge-base suites run a REAL in-memory database via node's
-          # built-in `node:sqlite` (__tests__/harness/sqliteFake.ts). That module is absent on
-          # Node 20 and flag-gated on Node 22. On Node 24 it loads but its native teardown
-          # SEGFAULTs the process under jest's --forceExit (exit 139) — reproduced locally: the
-          # full suite exits 139 on Node 24 and exits 0 on Node 26. Node 26's node:sqlite fixes
-          # that teardown crash, so the test runtime is pinned to 26.
+          # Node 26, pinned by the TEST gate and now shared by all of them. The RAG/knowledge-base
+          # suites run a REAL in-memory database via node's built-in `node:sqlite`
+          # (__tests__/harness/sqliteFake.ts). That module is absent on Node 20 and flag-gated on
+          # Node 22. On Node 24 it loads but its native teardown SEGFAULTs the process under jest's
+          # --forceExit (exit 139) — reproduced locally: the full suite exits 139 on Node 24 and
+          # exits 0 on Node 26. Node 26's node:sqlite fixes that teardown crash.
           node-version: '26'
           cache: 'npm'
 
@@ -151,24 +67,105 @@ jobs:
           distribution: 'temurin'
           java-version: '17'
 
-      - name: Install JS dependencies
+      # @offgrid/sync and @offgrid/rag are file: dependencies on the SIBLING shared monorepo
+      # ("file:../shared/packages/sync", "file:../shared/packages/rag"). They arrived with the sync
+      # work and nothing in CI ever provisioned them, so every gate failed on the same missing module
+      # wearing different hats: TS2307 in typecheck, 26 no-phantom-deps errors in the architecture
+      # gate, and 260 jest suites unable to resolve <workspace>/../shared/packages/sync/src/index.ts.
+      #
+      # actions/checkout refuses a path outside the workspace, so it lands inside and is moved up one
+      # level - which is exactly where the file: specifiers and jest's moduleNameMapper both point.
+      #
+      # Matching branch first, main as the fallback: a PR that changes the app and the shared package
+      # together has to be tested against the package it expects, not against main's copy.
+      - name: Check out the shared monorepo
+        if: ${{ env.PRO_SUBMODULE_PAT != '' }}
+        id: shared_branch
+        continue-on-error: true
+        uses: actions/checkout@v4
+        with:
+          repository: off-grid-ai/shared
+          token: ${{ env.PRO_SUBMODULE_PAT }}
+          path: _shared
+          ref: ${{ github.head_ref || github.ref_name }}
+          persist-credentials: false
+      - name: Fall back to shared main
+        if: ${{ env.PRO_SUBMODULE_PAT != '' && steps.shared_branch.outcome != 'success' }}
+        uses: actions/checkout@v4
+        with:
+          repository: off-grid-ai/shared
+          token: ${{ env.PRO_SUBMODULE_PAT }}
+          path: _shared
+          persist-credentials: false
+      - name: Put shared beside this checkout
+        if: ${{ env.PRO_SUBMODULE_PAT != '' }}
+        run: |
+          rm -rf ../shared
+          mv _shared ../shared
+          # Install at the WORKSPACE ROOT, not inside packages/sync. shared is an npm-workspaces
+          # monorepo: the lock file and the build tool (tsup) live at the root, and packages/sync
+          # declares neither. Installing inside the member failed `npm ci` (no lock file there), fell
+          # through to `npm install`, pulled the member's five runtime deps, and left the build to die
+          # on `sh: 1: tsup: not found` (exit 127) — which took every gate down with it.
+          #
+          # A LOCKED install, and no fallback. `npm ci || npm install` was here to survive a drifted lock, but
+          # that just moves the failure: an unlocked install resolves a different graph and the later gates run
+          # against dependencies nobody committed. The drift it papered over was real (five packages committed to
+          # shared without regenerating its lock) and is fixed at the source; if it recurs, this should stop.
+          npm --prefix ../shared ci
+          # Both packages this app consumes, because npm resolves each file: dep to its dist/ (jest
+          # reads src/, but tsc and metro read dist/). rag was never built at all before.
+          npm --prefix ../shared/packages/sync run build
+          npm --prefix ../shared/packages/rag run build
+
+      - name: Install dependencies
+        id: install
         run: npm ci
 
+      - name: Install SwiftLint
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: brew install swiftlint
+
+      # ── Gates. Every one runs even when an earlier one failed, so a single red gate cannot hide
+      # the rest; the job still fails if any of them do.
+      - name: Lint
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: npm run lint
+
+      - name: Type check
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: npx tsc --noEmit
+
+      # Standing gates: dependency-cruiser (layering, engine DIP, import cycles, orphans — 0
+      # violations, no baseline) + knip (dead files/exports/types/deps — 0 issues). Both fail on
+      # anything NEW.
+      - name: Dependency-cruiser (architecture gate)
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: npm run depcruise
+
+      - name: knip (dead-code gate)
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: npm run knip
+
       - name: Run Jest tests
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
         run: npx jest --coverage --forceExit --runInBand
 
       - name: Install Android NDK
         # Configuring the native modules (op-sqlite etc.) needs the pinned NDK; the macOS
         # runner doesn't ship it, so the android test task failed at configure with
         # "Failed to install ndk;...". Install the version android/build.gradle forces.
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
         run: |
           SDKMANAGER="$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager"
           yes | "$SDKMANAGER" "ndk;27.1.12297006" >/dev/null
 
       - name: Run Android tests
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
         run: cd android && ./gradlew :app:testDebugUnitTest --rerun-tasks
 
       - name: Run iOS tests
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
         run: |
           cd ios && xcodebuild test \
             -workspace OffgridMobile.xcworkspace \
@@ -178,6 +175,7 @@ jobs:
             2>&1 | (xcpretty 2>/dev/null || cat)
 
       - name: Upload coverage to Codecov
+        if: always()
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -207,6 +205,6 @@ jobs:
   # (see rules.md → On-device testing & verification). Docs-only / JS-only PRs don't need it.
 
   # NOTE: SonarCloud runs via Automatic Analysis (SonarCloud-side, on the public core project) —
-  # no CI job. A CI scan would only add coverage import, which Codecov (in the `test` job) already
-  # does, so it'd be redundant complexity. Pro is scanned locally by eslint-plugin-sonarjs (free,
-  # private, no leak). See docs/GAPS_BACKLOG.md.
+  # no CI job. A CI scan would only add coverage import, which Codecov already does, so it'd be
+  # redundant complexity. Pro is scanned locally by eslint-plugin-sonarjs (free, private, no leak).
+  # See docs/GAPS_BACKLOG.md.

App.tsx

@@ -18,7 +18,6 @@
 import { useDebugLogsStore } from './src/stores/debugLogsStore';
 import { initDebugLogFile, appendDebugLine } from './src/utils/debugLogFile';
 import { loadProFeatures } from './src/bootstrap/loadProFeatures';
-import { checkProStatus } from './src/services/proLicenseService';
 import { hydrateDownloadStore } from './src/services/downloadHydration';
 import { initActiveDownloadPersistence } from './src/services/activeDownloadPersistence';
 import { restoreQueuedDownloads } from './src/services/restoreQueuedDownloads';
@@ -200,7 +199,7 @@
     })().catch((error) => {
       logger.error('[App] Download-state recovery failed:', error);
     });
   }, [setDownloadedModels, setDownloadedImageModels]);
 
   const initializeApp = useCallback(async () => {
     try {
@@ -261,32 +260,12 @@
       // Initialize RAG database tables
       ragService.ensureReady().catch((err) => logger.error('Failed to initialize RAG service on startup', err));
 
-      // Read the cached Pro entitlement before Pro features load. checkProStatus
-      // returns the Keychain cache immediately and fires a background Keygen
-      // revalidation so the next launch stays fresh.
-      //
-      // Pro is optional: a failure here (keychain locked, no network) must never
-      // abort app init or hang the splash screen, so it is isolated and only logs.
-      let isPro = false;
       try {
-        isPro = await checkProStatus();
-      } catch (proError) {
-        logger.error('[App] Pro check failed, continuing without entitlement:', proError);
-      }
-
-      try {
-        // Load pro features — only activates if the keychain entitlement is set
-        // (or in dev, where loadProFeatures force-unlocks).
-        await loadProFeatures(isPro);
-
-        // Reconcile the persisted Pro flag with the actual entitlement on every
-        // boot. Setting it to the resolved value (not only ever true) means a
-        // cleared/expired license also flips it back to false — previously it
-        // only ever went true, so a stale persisted true stuck forever.
-        // DEV builds force-unlock for local testing, unless the Settings
-        // "Turn off Pro (DEV)" toggle is set. Never force-unlocks in release.
-        const devUnlock = __DEV__ && !useAppStore.getState().devProDisabled;
-        useAppStore.getState().setHasRegisteredPro(isPro || devUnlock);
+        // Register the private Pro entitlement provider before the first status
+        // read, then activate only the capabilities that entitlement permits.
+        // loadProFeatures separately projects cached credential access from a
+        // Debug developer unlock; Sync reconciliation owns device admission.
+        await loadProFeatures();
       } catch (proError) {
         logger.error('[App] Pro feature load failed, continuing without Pro:', proError);
       }