feat(amicus): v2 foundation — migrations, services, types, FK enforcement (2/3)

[CraigBuckmaster]

Part 2 of 3 — salvaging codex/amicus-auth-access-hardening

Foundation layer for the Amicus v2 work split out of codex/amicus-auth-access-hardening. No UI changes — every touched component is either a DB schema migration, a pure-function service, a type definition, or a test.

Stacks with:

• PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 (auth/access hardening) — independent, can merge in either order
• PR content(2_kings): coverage enrichment — 85 audit findings to zero #1659 (UI wiring, to follow) — depends on this PR

Why this is its own PR

The codex branch shipped these foundation pieces intermingled with 10 UI surfaces in one 58-file blob. Splitting them out gives us:

• A reviewable DB change surface (2 migrations + a PRAGMA change) evaluated on its own merits
• The ability to roll back UI wiring without losing the data model
• Clean test signal: foundation-layer tests aren't entangled with screen render tests

What's in

DB

• Migration 22 — amicus_thread_summaries — one row per thread, stores summary_text, last_user_intent, updated_at. Feeds the thread list so rows show meaningful labels without re-parsing every message.
• Migration 23 — amicus_thread_context — ties threads to guided-study sessions, specific steps, open questions, takeaways, key connections, and entry points. CHECK constraints on entry_point (fab|peek|thread|home_card|guided_study|my_study) and guided_step (scene|observe|explore|synthesize|review). FK references to amicus_threads (ON DELETE CASCADE) and guided_study_sessions / guided_study_questions (ON DELETE SET NULL). Two indexes tuned for recent-first lookups by (session, step) and by updated timestamp.
• PRAGMA foreign_keys = ON on every user-db connection open. Tier 2 fix from the senior review. SQLite leaves FK checks off by default and the setting is per-connection. Without it, every REFERENCES ... ON DELETE ... in our schema is cosmetic. This makes them real runtime constraints. Runs outside any transaction, before migrations, so migration DDL is unaffected — only DML that violates a declared FK gets rejected, which is what we want.

Services (all new, all pure functions)

File	What it does
services/amicus/context.ts	buildAmicusContextEnvelope, chapterRefFromChipContext, normalizeChapterRef, serializeAmicusChapterRef, formatAmicusContextLabel, prettyBookId. Shared envelope the Worker proxy receives + client-side formatting.
services/amicus/trust.ts	summarizeAmicusTrust reduces citations into source labels and stance; formatTrustStanceLabel.
services/amicus/threadIntelligence.ts	deriveThreadIntelligence derives title/summary/intent from first user query + guided-study context. shouldAutoRenameThread, summarizeLinkedQuestionState.
services/amicus/studyActions.ts	buildStudyActionSeeds enumerates one-tap actions for chapter-aware Amicus surfaces (explain_context, investigate_question, interpretive_tensions, refine_takeaway, trace_connections).
services/amicus/studyLaunch.ts	launchAmicusStudyThread resolves the right thread to open (dedup by question > session/step > chapter+entrypoint) and navigates. promotePeekToAmicusThread hydrates a peek session into a full thread.
services/amicus/deepLink.ts	formatChapterRef helper extended for the new envelope shape.
services/amicus/dailyPrompt.ts	Minor signature update to accept the enriched context.
services/amicus/index.ts	Barrel exports all of the above.

Types

• types/user.ts — AmicusThread extended with summary_text, last_user_intent, guided_step, open_question_id, guided_question_status, takeaway, key_connection (all hydrated by a single LEFT JOIN'd query). New AmicusThreadContextRecord and AmicusDraftMessage types.

Queries + mutations

• db/userQueries.ts — listAmicusThreads / getAmicusThread now LEFT JOIN amicus_thread_summaries, amicus_thread_context, and guided_study_questions so the UI can render enriched rows without N+1. New getters: getAmicusThreadContext, getLinkedGuidedStudyQuestionForThread, getAmicusThreadIdForGuided{Question,Session}, getLatestAmicusThreadIdForChapterContext, getLatestStudyAmicusThreadIdForChapter, getGuidedStudyQuestionForSession.
• db/userMutations.ts — upsertAmicusThreadContext and upsertAmicusThreadSummary (proper ON CONFLICT DO UPDATE SET … = excluded.*). reopenGuidedStudyQuestion. deleteAmicusThread wrapped in a transaction with explicit amicus_thread_context delete (redundant with FK cascade now ON, but defensive against DBs that predated this PR's pragma). resetToNewUser extended. createAmicusThread uses serializeAmicusChapterRef.
• Not in this PR: the emitAmicusUsageChanged calls in incrementAmicusUsage / clearAllAmicusData — those belong with the subscription in PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 and are stripped here to keep the PRs independent.

Tests

• New: services/amicus/__tests__/ for context, trust, threadIntelligence, studyActions, studyLaunch
• Extended: deepLink, db/amicus/mutations + queries, utils/routeContext, db/userDatabaseV3 (migrations 22/23)

Tier 2 fix included

PRAGMA foreign_keys = ON — turns the FK references in migrations 22/23 (and all prior migrations that have declared FKs) into actual runtime constraints. Flagged during the senior review as a pre-existing latent issue this branch was amplifying; fixing it here makes the new schema honest.

Risks

FK enforcement on existing DBs. If earlier bugs wrote orphan rows that violate a declared FK, those rows stay (SQLite doesn't retroactively scan) — but any new operation that tries to reference a missing parent will start failing. Low risk in practice: existing migrations declare few FKs and those reference well-populated tables. Worth a simulator smoke pass on a user.db that has real-world usage before cutting a release.

Out of scope (moves to PR 3)

• All UI components, hooks, screens, and navigation types
• StudySessionScreen.tsx changes (which must preserve fix(guided-study): stepper taps no longer bounce back to initialStep #1654's useRef bounce-back guard)
• MyStudyScreen.tsx changes (deferred per Guided Study: current UX is a framework, not a guided flow — capture current state and re-plan #1652's re-plan)

Test plan

• tsc --noEmit + jest via CI
• Manual smoke (rentamac iOS simulator):
  1. First launch — new user-db gets migrations 22/23 applied; sqlite_master shows both tables + both indexes
  2. PRAGMA foreign_keys returns 1 on a fresh connection
  3. Manually insert a bad FK (e.g. INSERT INTO amicus_thread_context(thread_id, entry_point) VALUES ('nope', 'fab')) — expect SQLITE_CONSTRAINT
  4. Delete an amicus_threads row that has a matching amicus_thread_context — verify CASCADE fires (context row gone)
  5. Existing app surfaces (notes, bookmarks, reading progress) continue to work — smoke each of the main screens

Rollback

Single-commit revert. Migrations 22 and 23 stay in sqlite_master (SQLite doesn't run migrations in reverse), but the code that reads/writes them is gone so the tables become inert. New thread-context/summary rows stop being written; existing ones orphan harmlessly. FK pragma goes back to off on the next release. No user data loss.

[github-actions]

⚠️Tests: Could not parse results

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3670	❌ 0	3670
Suites	✅ 498	❌ 0	498

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 91.3s

[CraigBuckmaster]

Part 2 of 3 — salvaging codex/amicus-auth-access-hardening

Foundation layer for the Amicus v2 work split out of codex/amicus-auth-access-hardening. No UI changes — every touched component is either a DB schema migration, a pure-function service, a type definition, or a test.

Stacks with:

• PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 (auth/access hardening) — independent, can merge in either order
• PR content(2_kings): coverage enrichment — 85 audit findings to zero #1659 (UI wiring, to follow) — depends on this PR

Why this is its own PR

The codex branch shipped these foundation pieces intermingled with 10 UI surfaces in one 58-file blob. Splitting them out gives us:

• A reviewable DB change surface (2 migrations + a PRAGMA change) evaluated on its own merits
• The ability to roll back UI wiring without losing the data model
• Clean test signal: foundation-layer tests aren't entangled with screen render tests

What's in

DB

• Migration 22 — amicus_thread_summaries — one row per thread, stores summary_text, last_user_intent, updated_at. Feeds the thread list so rows show meaningful labels without re-parsing every message.
• Migration 23 — amicus_thread_context — ties threads to guided-study sessions, specific steps, open questions, takeaways, key connections, and entry points. CHECK constraints on entry_point (fab|peek|thread|home_card|guided_study|my_study) and guided_step (scene|observe|explore|synthesize|review). FK references to amicus_threads (ON DELETE CASCADE) and guided_study_sessions / guided_study_questions (ON DELETE SET NULL). Two indexes tuned for recent-first lookups by (session, step) and by updated timestamp.
• PRAGMA foreign_keys = ON on every user-db connection open. Tier 2 fix from the senior review. SQLite leaves FK checks off by default and the setting is per-connection. Without it, every REFERENCES ... ON DELETE ... in our schema is cosmetic. This makes them real runtime constraints. Runs outside any transaction, before migrations, so migration DDL is unaffected — only DML that violates a declared FK gets rejected, which is what we want.

Services (all new, all pure functions)

File	What it does
services/amicus/context.ts	buildAmicusContextEnvelope, chapterRefFromChipContext, normalizeChapterRef, serializeAmicusChapterRef, formatAmicusContextLabel, prettyBookId. Shared envelope the Worker proxy receives + client-side formatting.
services/amicus/trust.ts	summarizeAmicusTrust reduces citations into source labels and stance; formatTrustStanceLabel.
services/amicus/threadIntelligence.ts	deriveThreadIntelligence derives title/summary/intent from first user query + guided-study context. shouldAutoRenameThread, summarizeLinkedQuestionState.
services/amicus/studyActions.ts	buildStudyActionSeeds enumerates one-tap actions for chapter-aware Amicus surfaces (explain_context, investigate_question, interpretive_tensions, refine_takeaway, trace_connections).
services/amicus/studyLaunch.ts	launchAmicusStudyThread resolves the right thread to open (dedup by question > session/step > chapter+entrypoint) and navigates. promotePeekToAmicusThread hydrates a peek session into a full thread.
services/amicus/deepLink.ts	formatChapterRef helper extended for the new envelope shape.
services/amicus/dailyPrompt.ts	Minor signature update to accept the enriched context.
services/amicus/index.ts	Barrel exports all of the above.

Types

• types/user.ts — AmicusThread extended with summary_text, last_user_intent, guided_step, open_question_id, guided_question_status, takeaway, key_connection (all hydrated by a single LEFT JOIN'd query). New AmicusThreadContextRecord and AmicusDraftMessage types.

Queries + mutations

• db/userQueries.ts — listAmicusThreads / getAmicusThread now LEFT JOIN amicus_thread_summaries, amicus_thread_context, and guided_study_questions so the UI can render enriched rows without N+1. New getters: getAmicusThreadContext, getLinkedGuidedStudyQuestionForThread, getAmicusThreadIdForGuided{Question,Session}, getLatestAmicusThreadIdForChapterContext, getLatestStudyAmicusThreadIdForChapter, getGuidedStudyQuestionForSession.
• db/userMutations.ts — upsertAmicusThreadContext and upsertAmicusThreadSummary (proper ON CONFLICT DO UPDATE SET … = excluded.*). reopenGuidedStudyQuestion. deleteAmicusThread wrapped in a transaction with explicit amicus_thread_context delete (redundant with FK cascade now ON, but defensive against DBs that predated this PR's pragma). resetToNewUser extended. createAmicusThread uses serializeAmicusChapterRef.
• Not in this PR: the emitAmicusUsageChanged calls in incrementAmicusUsage / clearAllAmicusData — those belong with the subscription in PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 and are stripped here to keep the PRs independent.

Tests

• New: services/amicus/__tests__/ for context, trust, threadIntelligence, studyActions, studyLaunch
• Extended: deepLink, db/amicus/mutations + queries, utils/routeContext, db/userDatabaseV3 (migrations 22/23)

Tier 2 fix included

PRAGMA foreign_keys = ON — turns the FK references in migrations 22/23 (and all prior migrations that have declared FKs) into actual runtime constraints. Flagged during the senior review as a pre-existing latent issue this branch was amplifying; fixing it here makes the new schema honest.

Risks

FK enforcement on existing DBs. If earlier bugs wrote orphan rows that violate a declared FK, those rows stay (SQLite doesn't retroactively scan) — but any new operation that tries to reference a missing parent will start failing. Low risk in practice: existing migrations declare few FKs and those reference well-populated tables. Worth a simulator smoke pass on a user.db that has real-world usage before cutting a release.

Out of scope (moves to PR 3)

• All UI components, hooks, screens, and navigation types
• StudySessionScreen.tsx changes (which must preserve fix(guided-study): stepper taps no longer bounce back to initialStep #1654's useRef bounce-back guard)
• MyStudyScreen.tsx changes (deferred per Guided Study: current UX is a framework, not a guided flow — capture current state and re-plan #1652's re-plan)

Test plan

• tsc --noEmit + jest via CI
• Manual smoke (rentamac iOS simulator):
  1. First launch — new user-db gets migrations 22/23 applied; sqlite_master shows both tables + both indexes
  2. PRAGMA foreign_keys returns 1 on a fresh connection
  3. Manually insert a bad FK (e.g. INSERT INTO amicus_thread_context(thread_id, entry_point) VALUES ('nope', 'fab')) — expect SQLITE_CONSTRAINT
  4. Delete an amicus_threads row that has a matching amicus_thread_context — verify CASCADE fires (context row gone)
  5. Existing app surfaces (notes, bookmarks, reading progress) continue to work — smoke each of the main screens

Rollback

Single-commit revert. Migrations 22 and 23 stay in sqlite_master (SQLite doesn't run migrations in reverse), but the code that reads/writes them is gone so the tables become inert. New thread-context/summary rows stop being written; existing ones orphan harmlessly. FK pragma goes back to off on the next release. No user data loss.

[github-actions]

⚠️Tests: Could not parse results

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3670	❌ 0	3670
Suites	✅ 498	❌ 0	498

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 91.3s

[CraigBuckmaster]

Part 2 of 3 — salvaging codex/amicus-auth-access-hardening

Foundation layer for the Amicus v2 work split out of codex/amicus-auth-access-hardening. No UI changes — every touched component is either a DB schema migration, a pure-function service, a type definition, or a test.

Stacks with:

• PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 (auth/access hardening) — independent, can merge in either order
• PR content(2_kings): coverage enrichment — 85 audit findings to zero #1659 (UI wiring, to follow) — depends on this PR

Why this is its own PR

The codex branch shipped these foundation pieces intermingled with 10 UI surfaces in one 58-file blob. Splitting them out gives us:

• A reviewable DB change surface (2 migrations + a PRAGMA change) evaluated on its own merits
• The ability to roll back UI wiring without losing the data model
• Clean test signal: foundation-layer tests aren't entangled with screen render tests

What's in

DB

• Migration 22 — amicus_thread_summaries — one row per thread, stores summary_text, last_user_intent, updated_at. Feeds the thread list so rows show meaningful labels without re-parsing every message.
• Migration 23 — amicus_thread_context — ties threads to guided-study sessions, specific steps, open questions, takeaways, key connections, and entry points. CHECK constraints on entry_point (fab|peek|thread|home_card|guided_study|my_study) and guided_step (scene|observe|explore|synthesize|review). FK references to amicus_threads (ON DELETE CASCADE) and guided_study_sessions / guided_study_questions (ON DELETE SET NULL). Two indexes tuned for recent-first lookups by (session, step) and by updated timestamp.
• PRAGMA foreign_keys = ON on every user-db connection open. Tier 2 fix from the senior review. SQLite leaves FK checks off by default and the setting is per-connection. Without it, every REFERENCES ... ON DELETE ... in our schema is cosmetic. This makes them real runtime constraints. Runs outside any transaction, before migrations, so migration DDL is unaffected — only DML that violates a declared FK gets rejected, which is what we want.

Services (all new, all pure functions)

File	What it does
services/amicus/context.ts	buildAmicusContextEnvelope, chapterRefFromChipContext, normalizeChapterRef, serializeAmicusChapterRef, formatAmicusContextLabel, prettyBookId. Shared envelope the Worker proxy receives + client-side formatting.
services/amicus/trust.ts	summarizeAmicusTrust reduces citations into source labels and stance; formatTrustStanceLabel.
services/amicus/threadIntelligence.ts	deriveThreadIntelligence derives title/summary/intent from first user query + guided-study context. shouldAutoRenameThread, summarizeLinkedQuestionState.
services/amicus/studyActions.ts	buildStudyActionSeeds enumerates one-tap actions for chapter-aware Amicus surfaces (explain_context, investigate_question, interpretive_tensions, refine_takeaway, trace_connections).
services/amicus/studyLaunch.ts	launchAmicusStudyThread resolves the right thread to open (dedup by question > session/step > chapter+entrypoint) and navigates. promotePeekToAmicusThread hydrates a peek session into a full thread.
services/amicus/deepLink.ts	formatChapterRef helper extended for the new envelope shape.
services/amicus/dailyPrompt.ts	Minor signature update to accept the enriched context.
services/amicus/index.ts	Barrel exports all of the above.

Types

• types/user.ts — AmicusThread extended with summary_text, last_user_intent, guided_step, open_question_id, guided_question_status, takeaway, key_connection (all hydrated by a single LEFT JOIN'd query). New AmicusThreadContextRecord and AmicusDraftMessage types.

Queries + mutations

• db/userQueries.ts — listAmicusThreads / getAmicusThread now LEFT JOIN amicus_thread_summaries, amicus_thread_context, and guided_study_questions so the UI can render enriched rows without N+1. New getters: getAmicusThreadContext, getLinkedGuidedStudyQuestionForThread, getAmicusThreadIdForGuided{Question,Session}, getLatestAmicusThreadIdForChapterContext, getLatestStudyAmicusThreadIdForChapter, getGuidedStudyQuestionForSession.
• db/userMutations.ts — upsertAmicusThreadContext and upsertAmicusThreadSummary (proper ON CONFLICT DO UPDATE SET … = excluded.*). reopenGuidedStudyQuestion. deleteAmicusThread wrapped in a transaction with explicit amicus_thread_context delete (redundant with FK cascade now ON, but defensive against DBs that predated this PR's pragma). resetToNewUser extended. createAmicusThread uses serializeAmicusChapterRef.
• Not in this PR: the emitAmicusUsageChanged calls in incrementAmicusUsage / clearAllAmicusData — those belong with the subscription in PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 and are stripped here to keep the PRs independent.

Tests

• New: services/amicus/__tests__/ for context, trust, threadIntelligence, studyActions, studyLaunch
• Extended: deepLink, db/amicus/mutations + queries, utils/routeContext, db/userDatabaseV3 (migrations 22/23)

Tier 2 fix included

PRAGMA foreign_keys = ON — turns the FK references in migrations 22/23 (and all prior migrations that have declared FKs) into actual runtime constraints. Flagged during the senior review as a pre-existing latent issue this branch was amplifying; fixing it here makes the new schema honest.

Risks

FK enforcement on existing DBs. If earlier bugs wrote orphan rows that violate a declared FK, those rows stay (SQLite doesn't retroactively scan) — but any new operation that tries to reference a missing parent will start failing. Low risk in practice: existing migrations declare few FKs and those reference well-populated tables. Worth a simulator smoke pass on a user.db that has real-world usage before cutting a release.

Out of scope (moves to PR 3)

• All UI components, hooks, screens, and navigation types
• StudySessionScreen.tsx changes (which must preserve fix(guided-study): stepper taps no longer bounce back to initialStep #1654's useRef bounce-back guard)
• MyStudyScreen.tsx changes (deferred per Guided Study: current UX is a framework, not a guided flow — capture current state and re-plan #1652's re-plan)

Test plan

• tsc --noEmit + jest via CI
• Manual smoke (rentamac iOS simulator):
  1. First launch — new user-db gets migrations 22/23 applied; sqlite_master shows both tables + both indexes
  2. PRAGMA foreign_keys returns 1 on a fresh connection
  3. Manually insert a bad FK (e.g. INSERT INTO amicus_thread_context(thread_id, entry_point) VALUES ('nope', 'fab')) — expect SQLITE_CONSTRAINT
  4. Delete an amicus_threads row that has a matching amicus_thread_context — verify CASCADE fires (context row gone)
  5. Existing app surfaces (notes, bookmarks, reading progress) continue to work — smoke each of the main screens

Rollback

Single-commit revert. Migrations 22 and 23 stay in sqlite_master (SQLite doesn't run migrations in reverse), but the code that reads/writes them is gone so the tables become inert. New thread-context/summary rows stop being written; existing ones orphan harmlessly. FK pragma goes back to off on the next release. No user data loss.

[github-actions]

⚠️Tests: Could not parse results

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3670	❌ 0	3670
Suites	✅ 498	❌ 0	498

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 91.3s

[CraigBuckmaster]

Part 2 of 3 — salvaging codex/amicus-auth-access-hardening

Foundation layer for the Amicus v2 work split out of codex/amicus-auth-access-hardening. No UI changes — every touched component is either a DB schema migration, a pure-function service, a type definition, or a test.

Stacks with:

• PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 (auth/access hardening) — independent, can merge in either order
• PR content(2_kings): coverage enrichment — 85 audit findings to zero #1659 (UI wiring, to follow) — depends on this PR

Why this is its own PR

The codex branch shipped these foundation pieces intermingled with 10 UI surfaces in one 58-file blob. Splitting them out gives us:

• A reviewable DB change surface (2 migrations + a PRAGMA change) evaluated on its own merits
• The ability to roll back UI wiring without losing the data model
• Clean test signal: foundation-layer tests aren't entangled with screen render tests

What's in

DB

• Migration 22 — amicus_thread_summaries — one row per thread, stores summary_text, last_user_intent, updated_at. Feeds the thread list so rows show meaningful labels without re-parsing every message.
• Migration 23 — amicus_thread_context — ties threads to guided-study sessions, specific steps, open questions, takeaways, key connections, and entry points. CHECK constraints on entry_point (fab|peek|thread|home_card|guided_study|my_study) and guided_step (scene|observe|explore|synthesize|review). FK references to amicus_threads (ON DELETE CASCADE) and guided_study_sessions / guided_study_questions (ON DELETE SET NULL). Two indexes tuned for recent-first lookups by (session, step) and by updated timestamp.
• PRAGMA foreign_keys = ON on every user-db connection open. Tier 2 fix from the senior review. SQLite leaves FK checks off by default and the setting is per-connection. Without it, every REFERENCES ... ON DELETE ... in our schema is cosmetic. This makes them real runtime constraints. Runs outside any transaction, before migrations, so migration DDL is unaffected — only DML that violates a declared FK gets rejected, which is what we want.

Services (all new, all pure functions)

File	What it does
services/amicus/context.ts	buildAmicusContextEnvelope, chapterRefFromChipContext, normalizeChapterRef, serializeAmicusChapterRef, formatAmicusContextLabel, prettyBookId. Shared envelope the Worker proxy receives + client-side formatting.
services/amicus/trust.ts	summarizeAmicusTrust reduces citations into source labels and stance; formatTrustStanceLabel.
services/amicus/threadIntelligence.ts	deriveThreadIntelligence derives title/summary/intent from first user query + guided-study context. shouldAutoRenameThread, summarizeLinkedQuestionState.
services/amicus/studyActions.ts	buildStudyActionSeeds enumerates one-tap actions for chapter-aware Amicus surfaces (explain_context, investigate_question, interpretive_tensions, refine_takeaway, trace_connections).
services/amicus/studyLaunch.ts	launchAmicusStudyThread resolves the right thread to open (dedup by question > session/step > chapter+entrypoint) and navigates. promotePeekToAmicusThread hydrates a peek session into a full thread.
services/amicus/deepLink.ts	formatChapterRef helper extended for the new envelope shape.
services/amicus/dailyPrompt.ts	Minor signature update to accept the enriched context.
services/amicus/index.ts	Barrel exports all of the above.

Types

• types/user.ts — AmicusThread extended with summary_text, last_user_intent, guided_step, open_question_id, guided_question_status, takeaway, key_connection (all hydrated by a single LEFT JOIN'd query). New AmicusThreadContextRecord and AmicusDraftMessage types.

Queries + mutations

• db/userQueries.ts — listAmicusThreads / getAmicusThread now LEFT JOIN amicus_thread_summaries, amicus_thread_context, and guided_study_questions so the UI can render enriched rows without N+1. New getters: getAmicusThreadContext, getLinkedGuidedStudyQuestionForThread, getAmicusThreadIdForGuided{Question,Session}, getLatestAmicusThreadIdForChapterContext, getLatestStudyAmicusThreadIdForChapter, getGuidedStudyQuestionForSession.
• db/userMutations.ts — upsertAmicusThreadContext and upsertAmicusThreadSummary (proper ON CONFLICT DO UPDATE SET … = excluded.*). reopenGuidedStudyQuestion. deleteAmicusThread wrapped in a transaction with explicit amicus_thread_context delete (redundant with FK cascade now ON, but defensive against DBs that predated this PR's pragma). resetToNewUser extended. createAmicusThread uses serializeAmicusChapterRef.
• Not in this PR: the emitAmicusUsageChanged calls in incrementAmicusUsage / clearAllAmicusData — those belong with the subscription in PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 and are stripped here to keep the PRs independent.

Tests

• New: services/amicus/__tests__/ for context, trust, threadIntelligence, studyActions, studyLaunch
• Extended: deepLink, db/amicus/mutations + queries, utils/routeContext, db/userDatabaseV3 (migrations 22/23)

Tier 2 fix included

PRAGMA foreign_keys = ON — turns the FK references in migrations 22/23 (and all prior migrations that have declared FKs) into actual runtime constraints. Flagged during the senior review as a pre-existing latent issue this branch was amplifying; fixing it here makes the new schema honest.

Risks

FK enforcement on existing DBs. If earlier bugs wrote orphan rows that violate a declared FK, those rows stay (SQLite doesn't retroactively scan) — but any new operation that tries to reference a missing parent will start failing. Low risk in practice: existing migrations declare few FKs and those reference well-populated tables. Worth a simulator smoke pass on a user.db that has real-world usage before cutting a release.

Out of scope (moves to PR 3)

• All UI components, hooks, screens, and navigation types
• StudySessionScreen.tsx changes (which must preserve fix(guided-study): stepper taps no longer bounce back to initialStep #1654's useRef bounce-back guard)
• MyStudyScreen.tsx changes (deferred per Guided Study: current UX is a framework, not a guided flow — capture current state and re-plan #1652's re-plan)

Test plan

• tsc --noEmit + jest via CI
• Manual smoke (rentamac iOS simulator):
  1. First launch — new user-db gets migrations 22/23 applied; sqlite_master shows both tables + both indexes
  2. PRAGMA foreign_keys returns 1 on a fresh connection
  3. Manually insert a bad FK (e.g. INSERT INTO amicus_thread_context(thread_id, entry_point) VALUES ('nope', 'fab')) — expect SQLITE_CONSTRAINT
  4. Delete an amicus_threads row that has a matching amicus_thread_context — verify CASCADE fires (context row gone)
  5. Existing app surfaces (notes, bookmarks, reading progress) continue to work — smoke each of the main screens

Rollback

Single-commit revert. Migrations 22 and 23 stay in sqlite_master (SQLite doesn't run migrations in reverse), but the code that reads/writes them is gone so the tables become inert. New thread-context/summary rows stop being written; existing ones orphan harmlessly. FK pragma goes back to off on the next release. No user data loss.

[github-actions]

⚠️Tests: Could not parse results

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3670	❌ 0	3670
Suites	✅ 498	❌ 0	498

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 91.3s

[CraigBuckmaster]

Part 2 of 3 — salvaging codex/amicus-auth-access-hardening

Foundation layer for the Amicus v2 work split out of codex/amicus-auth-access-hardening. No UI changes — every touched component is either a DB schema migration, a pure-function service, a type definition, or a test.

Stacks with:

• PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 (auth/access hardening) — independent, can merge in either order
• PR content(2_kings): coverage enrichment — 85 audit findings to zero #1659 (UI wiring, to follow) — depends on this PR

Why this is its own PR

The codex branch shipped these foundation pieces intermingled with 10 UI surfaces in one 58-file blob. Splitting them out gives us:

• A reviewable DB change surface (2 migrations + a PRAGMA change) evaluated on its own merits
• The ability to roll back UI wiring without losing the data model
• Clean test signal: foundation-layer tests aren't entangled with screen render tests

What's in

DB

• Migration 22 — amicus_thread_summaries — one row per thread, stores summary_text, last_user_intent, updated_at. Feeds the thread list so rows show meaningful labels without re-parsing every message.
• Migration 23 — amicus_thread_context — ties threads to guided-study sessions, specific steps, open questions, takeaways, key connections, and entry points. CHECK constraints on entry_point (fab|peek|thread|home_card|guided_study|my_study) and guided_step (scene|observe|explore|synthesize|review). FK references to amicus_threads (ON DELETE CASCADE) and guided_study_sessions / guided_study_questions (ON DELETE SET NULL). Two indexes tuned for recent-first lookups by (session, step) and by updated timestamp.
• PRAGMA foreign_keys = ON on every user-db connection open. Tier 2 fix from the senior review. SQLite leaves FK checks off by default and the setting is per-connection. Without it, every REFERENCES ... ON DELETE ... in our schema is cosmetic. This makes them real runtime constraints. Runs outside any transaction, before migrations, so migration DDL is unaffected — only DML that violates a declared FK gets rejected, which is what we want.

Services (all new, all pure functions)

File	What it does
services/amicus/context.ts	buildAmicusContextEnvelope, chapterRefFromChipContext, normalizeChapterRef, serializeAmicusChapterRef, formatAmicusContextLabel, prettyBookId. Shared envelope the Worker proxy receives + client-side formatting.
services/amicus/trust.ts	summarizeAmicusTrust reduces citations into source labels and stance; formatTrustStanceLabel.
services/amicus/threadIntelligence.ts	deriveThreadIntelligence derives title/summary/intent from first user query + guided-study context. shouldAutoRenameThread, summarizeLinkedQuestionState.
services/amicus/studyActions.ts	buildStudyActionSeeds enumerates one-tap actions for chapter-aware Amicus surfaces (explain_context, investigate_question, interpretive_tensions, refine_takeaway, trace_connections).
services/amicus/studyLaunch.ts	launchAmicusStudyThread resolves the right thread to open (dedup by question > session/step > chapter+entrypoint) and navigates. promotePeekToAmicusThread hydrates a peek session into a full thread.
services/amicus/deepLink.ts	formatChapterRef helper extended for the new envelope shape.
services/amicus/dailyPrompt.ts	Minor signature update to accept the enriched context.
services/amicus/index.ts	Barrel exports all of the above.

Types

• types/user.ts — AmicusThread extended with summary_text, last_user_intent, guided_step, open_question_id, guided_question_status, takeaway, key_connection (all hydrated by a single LEFT JOIN'd query). New AmicusThreadContextRecord and AmicusDraftMessage types.

Queries + mutations

• db/userQueries.ts — listAmicusThreads / getAmicusThread now LEFT JOIN amicus_thread_summaries, amicus_thread_context, and guided_study_questions so the UI can render enriched rows without N+1. New getters: getAmicusThreadContext, getLinkedGuidedStudyQuestionForThread, getAmicusThreadIdForGuided{Question,Session}, getLatestAmicusThreadIdForChapterContext, getLatestStudyAmicusThreadIdForChapter, getGuidedStudyQuestionForSession.
• db/userMutations.ts — upsertAmicusThreadContext and upsertAmicusThreadSummary (proper ON CONFLICT DO UPDATE SET … = excluded.*). reopenGuidedStudyQuestion. deleteAmicusThread wrapped in a transaction with explicit amicus_thread_context delete (redundant with FK cascade now ON, but defensive against DBs that predated this PR's pragma). resetToNewUser extended. createAmicusThread uses serializeAmicusChapterRef.
• Not in this PR: the emitAmicusUsageChanged calls in incrementAmicusUsage / clearAllAmicusData — those belong with the subscription in PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 and are stripped here to keep the PRs independent.

Tests

• New: services/amicus/__tests__/ for context, trust, threadIntelligence, studyActions, studyLaunch
• Extended: deepLink, db/amicus/mutations + queries, utils/routeContext, db/userDatabaseV3 (migrations 22/23)

Tier 2 fix included

PRAGMA foreign_keys = ON — turns the FK references in migrations 22/23 (and all prior migrations that have declared FKs) into actual runtime constraints. Flagged during the senior review as a pre-existing latent issue this branch was amplifying; fixing it here makes the new schema honest.

Risks

FK enforcement on existing DBs. If earlier bugs wrote orphan rows that violate a declared FK, those rows stay (SQLite doesn't retroactively scan) — but any new operation that tries to reference a missing parent will start failing. Low risk in practice: existing migrations declare few FKs and those reference well-populated tables. Worth a simulator smoke pass on a user.db that has real-world usage before cutting a release.

Out of scope (moves to PR 3)

• All UI components, hooks, screens, and navigation types
• StudySessionScreen.tsx changes (which must preserve fix(guided-study): stepper taps no longer bounce back to initialStep #1654's useRef bounce-back guard)
• MyStudyScreen.tsx changes (deferred per Guided Study: current UX is a framework, not a guided flow — capture current state and re-plan #1652's re-plan)

Test plan

• tsc --noEmit + jest via CI
• Manual smoke (rentamac iOS simulator):
  1. First launch — new user-db gets migrations 22/23 applied; sqlite_master shows both tables + both indexes
  2. PRAGMA foreign_keys returns 1 on a fresh connection
  3. Manually insert a bad FK (e.g. INSERT INTO amicus_thread_context(thread_id, entry_point) VALUES ('nope', 'fab')) — expect SQLITE_CONSTRAINT
  4. Delete an amicus_threads row that has a matching amicus_thread_context — verify CASCADE fires (context row gone)
  5. Existing app surfaces (notes, bookmarks, reading progress) continue to work — smoke each of the main screens

Rollback

Single-commit revert. Migrations 22 and 23 stay in sqlite_master (SQLite doesn't run migrations in reverse), but the code that reads/writes them is gone so the tables become inert. New thread-context/summary rows stop being written; existing ones orphan harmlessly. FK pragma goes back to off on the next release. No user data loss.

[github-actions]

⚠️Tests: Could not parse results

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3670	❌ 0	3670
Suites	✅ 498	❌ 0	498

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 91.3s

[CraigBuckmaster]

Part 2 of 3 — salvaging codex/amicus-auth-access-hardening

Foundation layer for the Amicus v2 work split out of codex/amicus-auth-access-hardening. No UI changes — every touched component is either a DB schema migration, a pure-function service, a type definition, or a test.

Stacks with:

• PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 (auth/access hardening) — independent, can merge in either order
• PR content(2_kings): coverage enrichment — 85 audit findings to zero #1659 (UI wiring, to follow) — depends on this PR

Why this is its own PR

The codex branch shipped these foundation pieces intermingled with 10 UI surfaces in one 58-file blob. Splitting them out gives us:

• A reviewable DB change surface (2 migrations + a PRAGMA change) evaluated on its own merits
• The ability to roll back UI wiring without losing the data model
• Clean test signal: foundation-layer tests aren't entangled with screen render tests

What's in

DB

• Migration 22 — amicus_thread_summaries — one row per thread, stores summary_text, last_user_intent, updated_at. Feeds the thread list so rows show meaningful labels without re-parsing every message.
• Migration 23 — amicus_thread_context — ties threads to guided-study sessions, specific steps, open questions, takeaways, key connections, and entry points. CHECK constraints on entry_point (fab|peek|thread|home_card|guided_study|my_study) and guided_step (scene|observe|explore|synthesize|review). FK references to amicus_threads (ON DELETE CASCADE) and guided_study_sessions / guided_study_questions (ON DELETE SET NULL). Two indexes tuned for recent-first lookups by (session, step) and by updated timestamp.
• PRAGMA foreign_keys = ON on every user-db connection open. Tier 2 fix from the senior review. SQLite leaves FK checks off by default and the setting is per-connection. Without it, every REFERENCES ... ON DELETE ... in our schema is cosmetic. This makes them real runtime constraints. Runs outside any transaction, before migrations, so migration DDL is unaffected — only DML that violates a declared FK gets rejected, which is what we want.

Services (all new, all pure functions)

File	What it does
services/amicus/context.ts	buildAmicusContextEnvelope, chapterRefFromChipContext, normalizeChapterRef, serializeAmicusChapterRef, formatAmicusContextLabel, prettyBookId. Shared envelope the Worker proxy receives + client-side formatting.
services/amicus/trust.ts	summarizeAmicusTrust reduces citations into source labels and stance; formatTrustStanceLabel.
services/amicus/threadIntelligence.ts	deriveThreadIntelligence derives title/summary/intent from first user query + guided-study context. shouldAutoRenameThread, summarizeLinkedQuestionState.
services/amicus/studyActions.ts	buildStudyActionSeeds enumerates one-tap actions for chapter-aware Amicus surfaces (explain_context, investigate_question, interpretive_tensions, refine_takeaway, trace_connections).
services/amicus/studyLaunch.ts	launchAmicusStudyThread resolves the right thread to open (dedup by question > session/step > chapter+entrypoint) and navigates. promotePeekToAmicusThread hydrates a peek session into a full thread.
services/amicus/deepLink.ts	formatChapterRef helper extended for the new envelope shape.
services/amicus/dailyPrompt.ts	Minor signature update to accept the enriched context.
services/amicus/index.ts	Barrel exports all of the above.

Types

• types/user.ts — AmicusThread extended with summary_text, last_user_intent, guided_step, open_question_id, guided_question_status, takeaway, key_connection (all hydrated by a single LEFT JOIN'd query). New AmicusThreadContextRecord and AmicusDraftMessage types.

Queries + mutations

• db/userQueries.ts — listAmicusThreads / getAmicusThread now LEFT JOIN amicus_thread_summaries, amicus_thread_context, and guided_study_questions so the UI can render enriched rows without N+1. New getters: getAmicusThreadContext, getLinkedGuidedStudyQuestionForThread, getAmicusThreadIdForGuided{Question,Session}, getLatestAmicusThreadIdForChapterContext, getLatestStudyAmicusThreadIdForChapter, getGuidedStudyQuestionForSession.
• db/userMutations.ts — upsertAmicusThreadContext and upsertAmicusThreadSummary (proper ON CONFLICT DO UPDATE SET … = excluded.*). reopenGuidedStudyQuestion. deleteAmicusThread wrapped in a transaction with explicit amicus_thread_context delete (redundant with FK cascade now ON, but defensive against DBs that predated this PR's pragma). resetToNewUser extended. createAmicusThread uses serializeAmicusChapterRef.
• Not in this PR: the emitAmicusUsageChanged calls in incrementAmicusUsage / clearAllAmicusData — those belong with the subscription in PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 and are stripped here to keep the PRs independent.

Tests

• New: services/amicus/__tests__/ for context, trust, threadIntelligence, studyActions, studyLaunch
• Extended: deepLink, db/amicus/mutations + queries, utils/routeContext, db/userDatabaseV3 (migrations 22/23)

Tier 2 fix included

PRAGMA foreign_keys = ON — turns the FK references in migrations 22/23 (and all prior migrations that have declared FKs) into actual runtime constraints. Flagged during the senior review as a pre-existing latent issue this branch was amplifying; fixing it here makes the new schema honest.

Risks

FK enforcement on existing DBs. If earlier bugs wrote orphan rows that violate a declared FK, those rows stay (SQLite doesn't retroactively scan) — but any new operation that tries to reference a missing parent will start failing. Low risk in practice: existing migrations declare few FKs and those reference well-populated tables. Worth a simulator smoke pass on a user.db that has real-world usage before cutting a release.

Out of scope (moves to PR 3)

• All UI components, hooks, screens, and navigation types
• StudySessionScreen.tsx changes (which must preserve fix(guided-study): stepper taps no longer bounce back to initialStep #1654's useRef bounce-back guard)
• MyStudyScreen.tsx changes (deferred per Guided Study: current UX is a framework, not a guided flow — capture current state and re-plan #1652's re-plan)

Test plan

• tsc --noEmit + jest via CI
• Manual smoke (rentamac iOS simulator):
  1. First launch — new user-db gets migrations 22/23 applied; sqlite_master shows both tables + both indexes
  2. PRAGMA foreign_keys returns 1 on a fresh connection
  3. Manually insert a bad FK (e.g. INSERT INTO amicus_thread_context(thread_id, entry_point) VALUES ('nope', 'fab')) — expect SQLITE_CONSTRAINT
  4. Delete an amicus_threads row that has a matching amicus_thread_context — verify CASCADE fires (context row gone)
  5. Existing app surfaces (notes, bookmarks, reading progress) continue to work — smoke each of the main screens

Rollback

Single-commit revert. Migrations 22 and 23 stay in sqlite_master (SQLite doesn't run migrations in reverse), but the code that reads/writes them is gone so the tables become inert. New thread-context/summary rows stop being written; existing ones orphan harmlessly. FK pragma goes back to off on the next release. No user data loss.

[github-actions]

⚠️Tests: Could not parse results

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3670	❌ 0	3670
Suites	✅ 498	❌ 0	498

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 91.3s

[CraigBuckmaster]

Part 2 of 3 — salvaging codex/amicus-auth-access-hardening

Foundation layer for the Amicus v2 work split out of codex/amicus-auth-access-hardening. No UI changes — every touched component is either a DB schema migration, a pure-function service, a type definition, or a test.

Stacks with:

• PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 (auth/access hardening) — independent, can merge in either order
• PR content(2_kings): coverage enrichment — 85 audit findings to zero #1659 (UI wiring, to follow) — depends on this PR

Why this is its own PR

The codex branch shipped these foundation pieces intermingled with 10 UI surfaces in one 58-file blob. Splitting them out gives us:

• A reviewable DB change surface (2 migrations + a PRAGMA change) evaluated on its own merits
• The ability to roll back UI wiring without losing the data model
• Clean test signal: foundation-layer tests aren't entangled with screen render tests

What's in

DB

• Migration 22 — amicus_thread_summaries — one row per thread, stores summary_text, last_user_intent, updated_at. Feeds the thread list so rows show meaningful labels without re-parsing every message.
• Migration 23 — amicus_thread_context — ties threads to guided-study sessions, specific steps, open questions, takeaways, key connections, and entry points. CHECK constraints on entry_point (fab|peek|thread|home_card|guided_study|my_study) and guided_step (scene|observe|explore|synthesize|review). FK references to amicus_threads (ON DELETE CASCADE) and guided_study_sessions / guided_study_questions (ON DELETE SET NULL). Two indexes tuned for recent-first lookups by (session, step) and by updated timestamp.
• PRAGMA foreign_keys = ON on every user-db connection open. Tier 2 fix from the senior review. SQLite leaves FK checks off by default and the setting is per-connection. Without it, every REFERENCES ... ON DELETE ... in our schema is cosmetic. This makes them real runtime constraints. Runs outside any transaction, before migrations, so migration DDL is unaffected — only DML that violates a declared FK gets rejected, which is what we want.

Services (all new, all pure functions)

File	What it does
services/amicus/context.ts	buildAmicusContextEnvelope, chapterRefFromChipContext, normalizeChapterRef, serializeAmicusChapterRef, formatAmicusContextLabel, prettyBookId. Shared envelope the Worker proxy receives + client-side formatting.
services/amicus/trust.ts	summarizeAmicusTrust reduces citations into source labels and stance; formatTrustStanceLabel.
services/amicus/threadIntelligence.ts	deriveThreadIntelligence derives title/summary/intent from first user query + guided-study context. shouldAutoRenameThread, summarizeLinkedQuestionState.
services/amicus/studyActions.ts	buildStudyActionSeeds enumerates one-tap actions for chapter-aware Amicus surfaces (explain_context, investigate_question, interpretive_tensions, refine_takeaway, trace_connections).
services/amicus/studyLaunch.ts	launchAmicusStudyThread resolves the right thread to open (dedup by question > session/step > chapter+entrypoint) and navigates. promotePeekToAmicusThread hydrates a peek session into a full thread.
services/amicus/deepLink.ts	formatChapterRef helper extended for the new envelope shape.
services/amicus/dailyPrompt.ts	Minor signature update to accept the enriched context.
services/amicus/index.ts	Barrel exports all of the above.

Types

• types/user.ts — AmicusThread extended with summary_text, last_user_intent, guided_step, open_question_id, guided_question_status, takeaway, key_connection (all hydrated by a single LEFT JOIN'd query). New AmicusThreadContextRecord and AmicusDraftMessage types.

Queries + mutations

• db/userQueries.ts — listAmicusThreads / getAmicusThread now LEFT JOIN amicus_thread_summaries, amicus_thread_context, and guided_study_questions so the UI can render enriched rows without N+1. New getters: getAmicusThreadContext, getLinkedGuidedStudyQuestionForThread, getAmicusThreadIdForGuided{Question,Session}, getLatestAmicusThreadIdForChapterContext, getLatestStudyAmicusThreadIdForChapter, getGuidedStudyQuestionForSession.
• db/userMutations.ts — upsertAmicusThreadContext and upsertAmicusThreadSummary (proper ON CONFLICT DO UPDATE SET … = excluded.*). reopenGuidedStudyQuestion. deleteAmicusThread wrapped in a transaction with explicit amicus_thread_context delete (redundant with FK cascade now ON, but defensive against DBs that predated this PR's pragma). resetToNewUser extended. createAmicusThread uses serializeAmicusChapterRef.
• Not in this PR: the emitAmicusUsageChanged calls in incrementAmicusUsage / clearAllAmicusData — those belong with the subscription in PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 and are stripped here to keep the PRs independent.

Tests

• New: services/amicus/__tests__/ for context, trust, threadIntelligence, studyActions, studyLaunch
• Extended: deepLink, db/amicus/mutations + queries, utils/routeContext, db/userDatabaseV3 (migrations 22/23)

Tier 2 fix included

PRAGMA foreign_keys = ON — turns the FK references in migrations 22/23 (and all prior migrations that have declared FKs) into actual runtime constraints. Flagged during the senior review as a pre-existing latent issue this branch was amplifying; fixing it here makes the new schema honest.

Risks

FK enforcement on existing DBs. If earlier bugs wrote orphan rows that violate a declared FK, those rows stay (SQLite doesn't retroactively scan) — but any new operation that tries to reference a missing parent will start failing. Low risk in practice: existing migrations declare few FKs and those reference well-populated tables. Worth a simulator smoke pass on a user.db that has real-world usage before cutting a release.

Out of scope (moves to PR 3)

• All UI components, hooks, screens, and navigation types
• StudySessionScreen.tsx changes (which must preserve fix(guided-study): stepper taps no longer bounce back to initialStep #1654's useRef bounce-back guard)
• MyStudyScreen.tsx changes (deferred per Guided Study: current UX is a framework, not a guided flow — capture current state and re-plan #1652's re-plan)

Test plan

• tsc --noEmit + jest via CI
• Manual smoke (rentamac iOS simulator):
  1. First launch — new user-db gets migrations 22/23 applied; sqlite_master shows both tables + both indexes
  2. PRAGMA foreign_keys returns 1 on a fresh connection
  3. Manually insert a bad FK (e.g. INSERT INTO amicus_thread_context(thread_id, entry_point) VALUES ('nope', 'fab')) — expect SQLITE_CONSTRAINT
  4. Delete an amicus_threads row that has a matching amicus_thread_context — verify CASCADE fires (context row gone)
  5. Existing app surfaces (notes, bookmarks, reading progress) continue to work — smoke each of the main screens

Rollback

Single-commit revert. Migrations 22 and 23 stay in sqlite_master (SQLite doesn't run migrations in reverse), but the code that reads/writes them is gone so the tables become inert. New thread-context/summary rows stop being written; existing ones orphan harmlessly. FK pragma goes back to off on the next release. No user data loss.

[github-actions]

⚠️Tests: Could not parse results

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3670	❌ 0	3670
Suites	✅ 498	❌ 0	498

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 91.3s

[CraigBuckmaster]

Part 2 of 3 — salvaging codex/amicus-auth-access-hardening

Foundation layer for the Amicus v2 work split out of codex/amicus-auth-access-hardening. No UI changes — every touched component is either a DB schema migration, a pure-function service, a type definition, or a test.

Stacks with:

• PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 (auth/access hardening) — independent, can merge in either order
• PR content(2_kings): coverage enrichment — 85 audit findings to zero #1659 (UI wiring, to follow) — depends on this PR

Why this is its own PR

The codex branch shipped these foundation pieces intermingled with 10 UI surfaces in one 58-file blob. Splitting them out gives us:

• A reviewable DB change surface (2 migrations + a PRAGMA change) evaluated on its own merits
• The ability to roll back UI wiring without losing the data model
• Clean test signal: foundation-layer tests aren't entangled with screen render tests

What's in

DB

• Migration 22 — amicus_thread_summaries — one row per thread, stores summary_text, last_user_intent, updated_at. Feeds the thread list so rows show meaningful labels without re-parsing every message.
• Migration 23 — amicus_thread_context — ties threads to guided-study sessions, specific steps, open questions, takeaways, key connections, and entry points. CHECK constraints on entry_point (fab|peek|thread|home_card|guided_study|my_study) and guided_step (scene|observe|explore|synthesize|review). FK references to amicus_threads (ON DELETE CASCADE) and guided_study_sessions / guided_study_questions (ON DELETE SET NULL). Two indexes tuned for recent-first lookups by (session, step) and by updated timestamp.
• PRAGMA foreign_keys = ON on every user-db connection open. Tier 2 fix from the senior review. SQLite leaves FK checks off by default and the setting is per-connection. Without it, every REFERENCES ... ON DELETE ... in our schema is cosmetic. This makes them real runtime constraints. Runs outside any transaction, before migrations, so migration DDL is unaffected — only DML that violates a declared FK gets rejected, which is what we want.

Services (all new, all pure functions)

File	What it does
services/amicus/context.ts	buildAmicusContextEnvelope, chapterRefFromChipContext, normalizeChapterRef, serializeAmicusChapterRef, formatAmicusContextLabel, prettyBookId. Shared envelope the Worker proxy receives + client-side formatting.
services/amicus/trust.ts	summarizeAmicusTrust reduces citations into source labels and stance; formatTrustStanceLabel.
services/amicus/threadIntelligence.ts	deriveThreadIntelligence derives title/summary/intent from first user query + guided-study context. shouldAutoRenameThread, summarizeLinkedQuestionState.
services/amicus/studyActions.ts	buildStudyActionSeeds enumerates one-tap actions for chapter-aware Amicus surfaces (explain_context, investigate_question, interpretive_tensions, refine_takeaway, trace_connections).
services/amicus/studyLaunch.ts	launchAmicusStudyThread resolves the right thread to open (dedup by question > session/step > chapter+entrypoint) and navigates. promotePeekToAmicusThread hydrates a peek session into a full thread.
services/amicus/deepLink.ts	formatChapterRef helper extended for the new envelope shape.
services/amicus/dailyPrompt.ts	Minor signature update to accept the enriched context.
services/amicus/index.ts	Barrel exports all of the above.

Types

• types/user.ts — AmicusThread extended with summary_text, last_user_intent, guided_step, open_question_id, guided_question_status, takeaway, key_connection (all hydrated by a single LEFT JOIN'd query). New AmicusThreadContextRecord and AmicusDraftMessage types.

Queries + mutations

• db/userQueries.ts — listAmicusThreads / getAmicusThread now LEFT JOIN amicus_thread_summaries, amicus_thread_context, and guided_study_questions so the UI can render enriched rows without N+1. New getters: getAmicusThreadContext, getLinkedGuidedStudyQuestionForThread, getAmicusThreadIdForGuided{Question,Session}, getLatestAmicusThreadIdForChapterContext, getLatestStudyAmicusThreadIdForChapter, getGuidedStudyQuestionForSession.
• db/userMutations.ts — upsertAmicusThreadContext and upsertAmicusThreadSummary (proper ON CONFLICT DO UPDATE SET … = excluded.*). reopenGuidedStudyQuestion. deleteAmicusThread wrapped in a transaction with explicit amicus_thread_context delete (redundant with FK cascade now ON, but defensive against DBs that predated this PR's pragma). resetToNewUser extended. createAmicusThread uses serializeAmicusChapterRef.
• Not in this PR: the emitAmicusUsageChanged calls in incrementAmicusUsage / clearAllAmicusData — those belong with the subscription in PR feat(amicus): harden auth access with RC init wiring (1/3) #1658 and are stripped here to keep the PRs independent.

Tests

• New: services/amicus/__tests__/ for context, trust, threadIntelligence, studyActions, studyLaunch
• Extended: deepLink, db/amicus/mutations + queries, utils/routeContext, db/userDatabaseV3 (migrations 22/23)

Tier 2 fix included

PRAGMA foreign_keys = ON — turns the FK references in migrations 22/23 (and all prior migrations that have declared FKs) into actual runtime constraints. Flagged during the senior review as a pre-existing latent issue this branch was amplifying; fixing it here makes the new schema honest.

Risks

FK enforcement on existing DBs. If earlier bugs wrote orphan rows that violate a declared FK, those rows stay (SQLite doesn't retroactively scan) — but any new operation that tries to reference a missing parent will start failing. Low risk in practice: existing migrations declare few FKs and those reference well-populated tables. Worth a simulator smoke pass on a user.db that has real-world usage before cutting a release.

Out of scope (moves to PR 3)

• All UI components, hooks, screens, and navigation types
• StudySessionScreen.tsx changes (which must preserve fix(guided-study): stepper taps no longer bounce back to initialStep #1654's useRef bounce-back guard)
• MyStudyScreen.tsx changes (deferred per Guided Study: current UX is a framework, not a guided flow — capture current state and re-plan #1652's re-plan)

Test plan

• tsc --noEmit + jest via CI
• Manual smoke (rentamac iOS simulator):
  1. First launch — new user-db gets migrations 22/23 applied; sqlite_master shows both tables + both indexes
  2. PRAGMA foreign_keys returns 1 on a fresh connection
  3. Manually insert a bad FK (e.g. INSERT INTO amicus_thread_context(thread_id, entry_point) VALUES ('nope', 'fab')) — expect SQLITE_CONSTRAINT
  4. Delete an amicus_threads row that has a matching amicus_thread_context — verify CASCADE fires (context row gone)
  5. Existing app surfaces (notes, bookmarks, reading progress) continue to work — smoke each of the main screens

Rollback

Single-commit revert. Migrations 22 and 23 stay in sqlite_master (SQLite doesn't run migrations in reverse), but the code that reads/writes them is gone so the tables become inert. New thread-context/summary rows stop being written; existing ones orphan harmlessly. FK pragma goes back to off on the next release. No user data loss.

[github-actions]

⚠️Tests: Could not parse results

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3670	❌ 0	3670
Suites	✅ 498	❌ 0	498

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 91.3s