refactor(parse-once): single-grammar reasoning + tool-call parsing, native-first for Gemma

.dependency-cruiser.js

@@ -0,0 +1,121 @@
+/**
+ * dependency-cruiser — the STANDING GATE for the architectural boundaries we keep
+ * re-establishing by hand in review (layering, engine DIP, dead code, cycles, dep hygiene).
+ *
+ * AGGRESSIVE by design: rules are strict and at `error`. It sees the IMPORT GRAPH, not values —
+ * so it enforces "a screen may not import a concrete engine service" (the SO2/SO4 class, at the
+ * bad import) and "utils/services may not import UI" (the DR1 backward-layering class), but it
+ * does NOT catch the `engine === 'litert'` VALUE branch (an ESLint no-restricted-syntax rule
+ * guards that) or DRY drift / logic bugs. Complements the hygiene standard; does not replace it.
+ *
+ * The tree is CLEAN — zero violations, no baseline file. Every rule is fully enforced with no
+ * exceptions; any new violation fails `npm run depcruise` (CI + pre-push). If you ever must adopt
+ * a new strict rule onto legacy debt, baseline it (`depcruise --output-type baseline >
+ * .dependency-cruiser-known-violations.json` + run the gate with `--ignore-known`) and burn it
+ * down — never regenerate a baseline to hide a fresh violation.
+ */
+module.exports = {
+  forbidden: [
+    // ── Architecture: layering + DIP ──────────────────────────────────────────
+    {
+      name: 'no-circular',
+      severity: 'error',
+      comment: 'Import cycles make load order undefined and desync-prone. Break the cycle (import the concrete module, not the barrel; extract shared state down a layer).',
+      from: {},
+      to: { circular: true },
+    },
+    {
+      name: 'no-backward-layering-core',
+      severity: 'error',
+      comment: 'Core (utils/services/stores/types/constants/config) must not import UI (screens/components/navigation). If a screen owns logic the core needs, move the logic DOWN (see DR1: parseModelOutput → utils).',
+      from: { path: '^src/(utils|services|stores|types|constants|config)/' },
+      to: { path: '^src/(screens|components|navigation)/' },
+    },
+    {
+      name: 'utils-stay-pure',
+      severity: 'error',
+      comment: 'src/utils is the zero-IO pure layer — it must not depend on services or stores. Pure logic here is unit-testable without mocking I/O (hygiene §A).',
+      from: { path: '^src/utils/' },
+      to: { path: '^src/(services|stores)/', pathNot: '^src/utils/' },
+    },
+    {
+      name: 'engine-dip-no-concrete-in-ui',
+      severity: 'error',
+      comment: 'UI (screens/components) must depend on the engine ABSTRACTION (services/engines), never a concrete engine service (services/litert, services/llm). Branching on a concrete engine in a caller is the DIP violation we keep fixing (SO2/SO4). Route through services/engines.',
+      from: { path: '^src/(screens|components)/' },
+      to: { path: '^src/services/(litert|llm)(/|\\.|$)' },
+    },
+    {
+      name: 'components-are-leaf-ui',
+      severity: 'error',
+      comment: 'Reusable components must not import screens or navigation — a leaf UI piece depending on a whole screen inverts the dependency and creates cycles. Lift shared bits into components/ or pass them in as props.',
+      from: { path: '^src/components/' },
+      to: { path: '^src/(screens|navigation)/' },
+    },
+    // ── Dead code ─────────────────────────────────────────────────────────────
+    {
+      name: 'no-orphans',
+      severity: 'error',
+      comment: 'Orphan module (no importers, imports nothing relevant) — dead code. Confirm with grep, then delete (the standing dead-code gate that retires the manual recon).',
+      from: {
+        orphan: true,
+        pathNot: [
+          '\\.(d\\.ts)$',
+          '(^|/)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
+        ],
+      },
+      to: {},
+    },
+    // ── Test / build hygiene ──────────────────────────────────────────────────
+    {
+      name: 'not-to-test-from-prod',
+      severity: 'error',
+      comment: 'Production code (src) must not import test files or test utilities — that ships test-only code (and its mocks) into the app bundle.',
+      from: { path: '^src/', pathNot: '\\.(test|spec)\\.[jt]sx?$' },
+      to: { path: '(\\.(test|spec)\\.[jt]sx?$|^(__tests__|__mocks__)/)' },
+    },
+    {
+      name: 'not-to-dev-dep',
+      severity: 'error',
+      comment: 'Production code (src) must not import a devDependency — it will be missing in the release bundle. Move the package to dependencies, or the import out of src.',
+      from: { path: '^src/', pathNot: '\\.(test|spec)\\.[jt]sx?$' },
+      to: { dependencyTypes: ['npm-dev'], pathNot: '(@types/|typescript$)' },
+    },
+    {
+      name: 'no-phantom-deps',
+      severity: 'error',
+      comment: 'Imports a package that is not declared in package.json (a phantom/transitive dependency) — it breaks the moment the transitive graph changes. Declare it explicitly.',
+      from: {},
+      to: {
+        dependencyTypes: ['unknown', 'undetermined', 'npm-no-pkg', 'npm-unknown'],
+        // Known non-resolvable-by-cruiser but LEGITIMATE: whisper.rn IS declared (^0.5.5) but the
+        // `.rn` name defeats cruiser's resolver; @offgrid/pro is the private open-core submodule
+        // wired via metro haste through the ONE bootstrap loader (loadProFeatures) — intentional,
+        // not a phantom dep. Neither is real debt, so exclude rather than baseline.
+        pathNot: '(^whisper\\.rn(/|$)|^@offgrid/pro(/|$))',
+      },
+    },
+    {
+      name: 'no-deprecated-core',
+      severity: 'warn',
+      comment: 'Depends on a deprecated Node core module (e.g. punycode) — will break on a future runtime. Replace it.',
+      from: {},
+      to: { dependencyTypes: ['core'], path: '^(punycode|domain|constants|sys|_linklist|_stream_wrap)$' },
+    },
+  ],
+  options: {
+    doNotFollow: { path: 'node_modules' },
+    tsPreCompilationDeps: true,
+    tsConfig: { fileName: 'tsconfig.json' },
+    enhancedResolveOptions: {
+      exportsFields: ['exports'],
+      conditionNames: ['import', 'require', 'node', 'default', 'types'],
+      extensions: ['.js', '.jsx', '.ts', '.tsx', '.json'],
+    },
+    reporterOptions: {
+      text: { highlightFocused: true },
+    },
+  },
+};

.eslintrc.js

@@ -1,10 +1,18 @@
 module.exports = {
   root: true,
-  extends: '@react-native',
+  extends: [
+    '@react-native',
+    // SonarJS: Sonar-grade bug/smell detection in normal lint — free, local, and it covers
+    // PRO too (pro has no cloud Sonar project; a private cloud project is paid-by-LOC). Most
+    // rules stay at `error` (recommended default) as a forward guard; the handful already
+    // tripped on legacy code are `warn` below with a logged burn-down (GAPS_BACKLOG).
+    'plugin:sonarjs/recommended-legacy',
+  ],
   plugins: [
     'react-native',
     'react',
     'react-hooks',
+    'sonarjs',
   ],
   env: {
     jest: true,
@@ -43,6 +51,20 @@ module.exports = {
     'react-native/no-color-literals': 'error',
     'react-native/no-raw-text': 'error',
     'react-native/no-single-element-style-arrays': 'error',
+
+    // SonarJS — every rule stays at the recommended `error` (a real forward guard on new code)
+    // EXCEPT the two handled here:
+    //  - no-duplicate-string OFF: it fights RN styling — 'space-between'/'center'/'row' and color
+    //    literals repeat by design across StyleSheet objects; a constant per style value is noise,
+    //    not clarity. The one low-value SonarJS rule for this codebase.
+    //  - the rest are `warn` (already tripped on legacy core; burn-down in docs/GAPS_BACKLOG.md,
+    //    ratchet each back to `error` as its count hits zero).
+    'sonarjs/no-duplicate-string': 'off',
+    'sonarjs/prefer-single-boolean-return': 'warn',
+    'sonarjs/no-nested-template-literals': 'warn',
+    'sonarjs/no-collapsible-if': 'warn',
+    'sonarjs/prefer-immediate-return': 'warn',
+    'sonarjs/no-duplicated-branches': 'warn',
   },
   overrides: [
     {
@@ -56,6 +78,11 @@ module.exports = {
         'react-native/no-inline-styles': 'off',
         'react-native/no-raw-text': 'off',
         'react-native/no-color-literals': 'off',
+        // Duplicate test bodies (identical arrange/act across cases) are acceptable and clearer
+        // than over-DRYing tests; the real-bug SonarJS rules (mischeck, unused-collection, etc.)
+        // stay ON for tests — they caught a tautology assertion + a dead collection here.
+        'sonarjs/no-identical-functions': 'off',
+        'sonarjs/cognitive-complexity': 'off',
       },
     },
   ],

.github/workflows/ci.yml

@@ -56,6 +56,27 @@ jobs:
       - name: Type check
         run: npx tsc --noEmit
 
+  architecture:
+    # Dependency-cruiser standing gate: fails on any NEW architectural violation beyond the
+    # baselined debt (layering, engine DIP, import cycles, orphans). See .dependency-cruiser.js.
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Dependency-cruiser (architecture gate)
+        run: npm run depcruise
+
   test:
     runs-on: macos-latest
 
@@ -173,3 +194,8 @@ jobs:
 
       - name: Build Android Release
         run: cd android && ./gradlew assembleRelease
+
+  # 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.

.husky/pre-push

@@ -49,6 +49,9 @@ if [ -n "$PUSHED_JS" ]; then
 
   echo "▶ JS/TS tests (related to changed files)..."
   echo "$PUSHED_JS" | tr '\n' '\0' | xargs -0 npx jest --findRelatedTests --passWithNoTests
+
+  echo "▶ Architecture gate (dependency-cruiser)..."
+  npm run depcruise
 fi
 
 if [ -n "$PUSHED_SWIFT" ]; then

CLAUDE.md

@@ -29,6 +29,16 @@ Then `grep`/read `/tmp/offgrid-debug.log`. The file appends a `===== session sta
 
 **Merge strategy: ALWAYS a merge commit. NEVER squash (and never rebase-merge).** When merging a PR, use `gh pr merge --merge` (or the "Create a merge commit" button) so the full commit history is preserved on `main`. Do not squash under any circumstances - the small, meaningful per-concern commits are the record and must survive the merge. This applies to both the core repo and the `pro` submodule.
 
+### Commit early, commit often - never lose progress (agents especially)
+
+**A long task is a chain of small, GREEN, committed steps - not one giant uncommitted diff.** Agents run against context/session limits; anything uncommitted is lost when the session ends. So:
+
+- **Commit each cohesive step as soon as it is green** (typecheck + the relevant tests pass), with a real per-concern message. A refactor done in slices commits after each slice, not at the end.
+- **Never leave a large uncommitted working tree across a risky/long operation.** If you are about to start something big, commit what already works first so there is a clean restore point.
+- **Every commit is a safe restore point:** it must be behavior-neutral-or-better and pass the gates for the files it touches. Do not commit a knowingly-broken tree; if mid-refactor is unavoidably broken, finish to green before committing (or stash), never push broken.
+- **Prefer many small commits over few large ones.** They survive a merge (we never squash), make review tractable, and mean a lost session costs one step, not the whole task.
+- This is not optional polish - it is how work is not lost. Treat "a lot of uncommitted changes" as a bug to fix immediately by landing them as small commits.
+
 ## Copy & Content Standards
 
 **Any change to website copy, essays, docs text, UI strings, or marketing content must follow the brand voice guide:**

__tests__/integration/audio/streamingStateMachine.test.ts

@@ -20,7 +20,6 @@ jest.mock('@offgrid/core/utils/logger', () => ({
 type SpeakMode = 'resolve' | 'hang' | 'throw';
 let speakMode: SpeakMode = 'resolve';
 let enginePhase = 'ready';
-const releasers: Array<() => void> = [];
 const mockEngine = {
   speak: jest.fn(() => {
     if (speakMode === 'throw') return Promise.reject(new Error('std::exception'));
@@ -68,7 +67,6 @@ beforeEach(async () => {
   speakMode = 'resolve';
   enginePhase = 'ready';
   mockCanLoad.mockReturnValue(false);
-  releasers.length = 0;
   // clearAllMocks resets call history but NOT implementations — restore the
   // speakMode-driven impl so a prior test's mockImplementation can't leak in.
   mockEngine.speak.mockImplementation(() => {

__tests__/integration/chat/reasoningPipeline.test.tsx

@@ -0,0 +1,123 @@
+/**
+ * INTEGRATION — the reasoning pipeline through its REAL seams, end to end.
+ *
+ * This is the test that proves the parse-once refactor actually works for a user, not that a
+ * mock returned what it was told. It drives the REAL chatStore (streaming → finalize) and the
+ * REAL ChatMessage render, with NOTHING mocked in the parse path, and asserts the observable
+ * outcome: reasoning is captured, the visible answer is clean, and raw model markup NEVER
+ * reaches the screen. It reproduces the two bugs this refactor closes:
+ *   - DR1  — remote channel reasoning leaking into the answer (streamed-split flow)
+ *   - OD14 / tool-call leak — raw <tool_call>/<function=…> markup shown as text
+ * for every format in the single-source grammar. A wall of green unit tests could not catch a
+ * wiring bug between stream → store → render; this can.
+ */
+import React from 'react';
+import { render } from '@testing-library/react-native';
+import { useChatStore } from '../../../src/stores/chatStore';
+import { ChatMessage } from '../../../src/components/ChatMessage';
+import { REASONING_DELIMITERS } from '../../../src/utils/messageContent';
+import { ThinkTagParser } from '../../../src/services/providers/openAICompatibleStream';
+import { resetStores, getChatState } from '../../utils/testHelpers';
+import type { Message } from '../../../src/types';
+
+const REASONING = 'let me weigh the options carefully';
+const ANSWER = 'Here is the clean answer.';
+
+/** Read the single assistant message the store just finalized into the active conversation. */
+function finalizedMessage(convId: string): Message {
+  const msg = getChatState()
+    .conversations.find(c => c.id === convId)
+    ?.messages.at(-1);
+  if (!msg) throw new Error('no finalized message');
+  return msg;
+}
+
+describe('reasoning pipeline — stream → finalize → render, real seams', () => {
+  beforeEach(() => resetStores());
+
+  describe.each(REASONING_DELIMITERS)(
+    'format opened by %j',
+    ({ open, close }) => {
+      const raw = `${open}${REASONING}${close}${ANSWER}`;
+
+      it('LOCAL flow: inline-tagged content is split into reasoning + clean answer, and renders both', () => {
+        const store = useChatStore.getState();
+        const convId = store.createConversation('local-model');
+        store.startStreaming(convId);
+        // Local (llama.rn) path: raw tokens accumulate in streamingMessage; reasoning is extracted
+        // at finalize by the ONE shared parser.
+        store.appendToStreamingMessage(raw);
+        store.finalizeStreamingMessage(convId);
+
+        const msg = finalizedMessage(convId);
+        expect(msg.reasoningContent).toBe(REASONING);
+        expect(msg.content).toBe(ANSWER);
+        // The stored answer carries none of the opener/closer markup.
+        expect(msg.content).not.toContain(open.trim());
+        expect(msg.content).not.toContain(close.trim());
+
+        const { getByText, queryByText } = render(
+          <ChatMessage message={msg} />,
+        );
+        expect(getByText(ANSWER)).toBeTruthy(); // clean answer is visible
+        expect(getByText(new RegExp(REASONING.slice(0, 20)))).toBeTruthy(); // reasoning survived into the block
+        expect(
+          queryByText(
+            new RegExp(open.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&')),
+          ),
+        ).toBeNull(); // no raw markup on screen
+      });
+
+      it('REMOTE flow: ThinkTagParser split → store → finalize keeps reasoning out of the answer (DR1)', () => {
+        const store = useChatStore.getState();
+        const convId = store.createConversation('remote-model');
+        store.startStreaming(convId);
+        // Remote (OpenAI-compatible) path: the streaming parser routes reasoning vs answer live,
+        // feeding the two store channels. Same grammar, different seam.
+        const parser = new ThinkTagParser();
+        parser.process(
+          raw,
+          t => useChatStore.getState().appendToStreamingMessage(t),
+          r => useChatStore.getState().appendToStreamingReasoningContent(r),
+        );
+        store.finalizeStreamingMessage(convId);
+
+        const msg = finalizedMessage(convId);
+        expect(msg.reasoningContent).toBe(REASONING);
+        expect(msg.content).toBe(ANSWER);
+
+        const { getByText, queryByText } = render(
+          <ChatMessage message={msg} />,
+        );
+        expect(getByText(ANSWER)).toBeTruthy();
+        expect(
+          queryByText(
+            new RegExp(open.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&')),
+          ),
+        ).toBeNull();
+      });
+    },
+  );
+
+  it('tool-call markup never reaches the stored answer or the screen (OD14 / leak class)', () => {
+    const store = useChatStore.getState();
+    const convId = store.createConversation('local-model');
+    store.startStreaming(convId);
+    // A model that emits its answer wrapped around raw tool-call markup. After finalize the
+    // stored content — and everything rendered — must be free of that markup.
+    store.appendToStreamingMessage(
+      'Sure, checking that.<tool_call><function=get_weather><parameter=city>NYC</parameter></function></tool_call>',
+    );
+    store.finalizeStreamingMessage(convId);
+
+    const msg = finalizedMessage(convId);
+    expect(msg.content).not.toContain('<tool_call>');
+    expect(msg.content).not.toContain('<function=');
+    expect(msg.content).not.toContain('<parameter=');
+
+    const { queryByText } = render(<ChatMessage message={msg} />);
+    expect(queryByText(/<tool_call>/)).toBeNull();
+    expect(queryByText(/<function=/)).toBeNull();
+    expect(queryByText(/<parameter=/)).toBeNull();
+  });
+});