feat(core): productize first-mention events + TLL EO read-path

[moralespanitz]

Summary

Productizes two architectural primitives previously prototyped in the BEAM benchmark harness:

1. First-mention events — chronological topic-introduction list as first-class memory objects (new table, repository, service, HTTP route)
2. TLL EO read-path — public API on the existing Temporal Linkage List (write-side already shipped); enriched event-chain queries with content joined

Both surface as new HTTP endpoints; both are gated and best-effort so existing pipelines are untouched. Type-check clean; new repo + integration tests pending DB run.

Branch base note: stacks on experiment/phase2-combined-stack (the active core experiment branch) because that branch and main have no common ancestor in the current repo state. Once experiment/phase2-combined-stack lands on main, this PR can be re-targeted.

Companion: atomicmemory-benchmarks PR #20 (link) where these primitives were prototyped harness-side. Today's cross-backbone gate experiment showed the +0.157 architecture lift on Haiku does not generalize to Sonnet 4.6 (regressed to 0.350); productizing the primitives makes them shippable independent of BEAM scoring while keeping cross-backbone variance as the headline finding.

What's new

TLL EO read-path

Change	File	Purpose
Static import	src/services/memory-search.ts	replaces dynamic await import('./tll-retrieval.js')
chainEventsForEntities()	src/db/repository-tll.ts	enriched events: memoryId, content, observationDate, positionInChain, predecessorMemoryId joined from memories table
getEventChains()	src/services/memory-service.ts	public service method; null-safe when TLL disabled
EventChainsQuerySchema	src/schemas/memories.ts	comma-separated UUID list, deduped, validated
EventChainsResponseSchema	src/schemas/responses.ts	shape contract
GET /v1/memories/event-chains?user_id=X&entity_ids=Y,Z	src/routes/memories.ts	new endpoint
Tests	src/services/__tests__/tll-retrieval.test.ts (26 cases) + src/db/__tests__/repository-tll.test.ts (13 tests)	unit tests for retrieval helpers + integration tests against test Postgres

Risk: LOW. TLL stays read-only augmentation; AUDN flow unaffected; NULL-predecessor handling preserved.

First-mention events productization

Change	File	Purpose
Schema migration	src/db/schema.sql	new first_mention_events table + 2 indexes (position, GIN(topic))
Repository	src/db/repository-first-mentions.ts (NEW, 119 lines)	FirstMentionRepository with store(), getByMemoryId(), list()
Service	src/services/first-mention-service.ts (NEW, 209 lines)	FirstMentionService.extractAndStore(). Single LLM call scans full transcript; salvage parser for truncated JSON; best-effort error handling
Composition root	src/app/runtime-container.ts	instantiate repo + service; ChatFn adapter wraps llm.chat singleton
MemoryService 9th param	src/services/memory-service.ts	optional firstMentionService; new public extractFirstMentions() method
Deps type	src/services/memory-service-types.ts	firstMentionService: FirstMentionService | null
Body schema	src/schemas/memories.ts	FirstMentionsExtractBodySchema accepts memory_ids_by_turn_id as Record<string, string> and transforms to Map<number, string>
Response schema	src/schemas/responses.ts	FirstMentionsExtractResponseSchema
Route	src/routes/memories.ts	POST /v1/memories/first-mentions/extract
Test fixture	src/services/__tests__/cross-workspace-coupling-fence.test.ts	adds firstMentionService: null
Tests	src/services/__tests__/first-mention-service.test.ts	9 unit tests covering happy path, salvage of truncated JSON, garbage fallback, schema validation, anchor-date parsing, sort

Why caller-driven extraction (no in-core ingest hook)

The in-core ingest pipeline does not retain turn structure (it extracts atomic facts from chunks, not turns). The BEAM harness — which knows turn structure — supplies the turn-id-to-memory-id mapping in the request body. Adding an automatic post-write hook is deferred to a follow-up once a core-side notion of "turn" exists. This keeps the extraction path explicit and the core ingest pipeline unchanged.

API additions

GET /v1/memories/event-chains?user_id=<uid>&entity_ids=<uuid1>,<uuid2>
→ { chains: [{ entity_id, events: [{ memory_id, content, observation_date, position_in_chain, predecessor_memory_id }, ...] }] }

POST /v1/memories/first-mentions/extract
Body: {
  user_id: string,
  conversation_text: string,
  source_site: string,
  memory_ids_by_turn_id: { [turnId: string]: string }
}
→ { events: [{ topic, turn_id, memory_id, anchor_date, position_in_conversation }, ...] }

Verification

• npx tsc --noEmit clean across all changes
• npm test (vitest with fileParallelism: false) — required pre-merge; needs dotenv -e .env.test Postgres set up
• fallow --no-cache if installed (skip with note otherwise)
• npm run migrate:test then npm run migrate on real DB before deploy

Test plan

• Reviewer runs npm test against test Postgres — expect new tests pass
• Reviewer runs migration on a clean test DB; confirms first_mention_events table created with (user_id, memory_id) UNIQUE + both indexes
• Reviewer hits GET /v1/memories/event-chains with a known UID + entity_ids; expects ordered enriched events
• Reviewer hits POST /v1/memories/first-mentions/extract with a sample conversation + memory_ids_by_turn_id; expects events JSON; verifies row in first_mention_events
• Reviewer confirms existing routes still pass schema validation

Out of scope (separate PRs)

• Harness refactor in atomicmemory-benchmarks/data/exp-stage7-beam-dryrun/lib.ts to call new core endpoint instead of local extractFirstMentions()
• In-core ingest-post-write hook (requires turn-structure abstraction)
• BEAM 1M / 10M evaluation (pre-committed kill after cross-backbone gate)
• Sonnet/Opus 3-conv multirun

Companion

• atomicmemory-benchmarks PR feat(infra): LiteLLM unified gateway for multi-provider LLM routing #20: https://github.com/atomicmemory/atomicmemory-benchmarks/pull/20

---

Merge readiness (target: main)

This section captures the state of the PR specifically as a candidate for merge into main, layered on top of the existing description above.

Pre-merge blockers

1. PR base is experiment/phase2-combined-stack, not main. Re-targeting the base to main is a hard requirement before a merge button to main makes sense. See blocker (2) for why a simple re-target is not sufficient on its own.
2. HEAD and origin/main share no common ancestor. Confirmed with git merge-base feature/first-mention-and-tll-productization origin/main (exit 1, no output). The two histories have separate root commits (754d9ac "Initial public release" vs 919752f "Initial commit"). A normal merge or rebase to main is not possible without an explicit --allow-unrelated-histories merge or a history reconciliation. This is a repo-wide situation, not specific to this PR — six other open PRs (feat(extraction): preserve first-person negations in extraction prompt #3–feat(search): EXP-14 — retrieval-side abstention gate #8) target main from branches that descend from the same 754d9ac lineage and would face the same constraint.
3. CI has not run on this PR. gh pr checks 17 returns "no checks reported on the 'feature/first-mention-and-tll-productization' branch". .github/workflows/ci.yml is configured to trigger on pull_request: branches: [main], so PRs targeting any non-main branch (including this one targeting experiment/phase2-combined-stack) do not trigger CI. Re-targeting to main would also unblock CI.
4. npm test not yet run against test Postgres. The PR body's verification checklist explicitly leaves this unchecked; the new repository-tll.test.ts (13 cases) needs .env.test Postgres. CI will cover this once (3) is unblocked. Local pre-commit verification was deliberately skipped in this audit — agent has been instructed not to touch the running core server.

Behavior changes for callers (vs main)

The PR body documents the delta vs the immediate base (phase2-combined-stack). The full delta vs main is larger because phase2-combined-stack itself has not landed on main. Net surface diff main..HEAD (across the full stack):

• New HTTP endpoints (this PR): GET /v1/memories/event-chains, POST /v1/memories/first-mentions/extract.
• New env flag (from earlier commit c84d7b8 in the stack): AUDN_LLM_DISABLED — when true, the AUDN flow short-circuits to ADD-only. Defaults false; backward-compatible.
• New env flag (from earlier commit 709242f): EXTRACTION_MAX_TOKENS raised 4096 → 8192 default. Backward-compatible.
• New env flag (from earlier commit edcbe0b): ANTHROPIC_LLM_TIMEOUT_MS (default 30000).
• New schema migration (this PR): first_mention_events table + 2 indexes.
• Other schema changes (from earlier commits in the stack): temporal_linkage_list table (commit d6bd5f8); migrations should be applied in order if/when this stack lands.
• Extraction prompt: atomic remains the default. Concept-faithful is opt-in via EXTRACTION_PROMPT_VARIANT=concept-faithful. No breaking change for existing callers.
• AUDN behavior: unchanged when AUDN_LLM_DISABLED is not set (default).

Test coverage for new code (this PR's commit only)

• 26 unit cases in src/services/__tests__/tll-retrieval.test.ts
• 13 integration cases in src/db/__tests__/repository-tll.test.ts
• 9 unit cases in src/services/__tests__/first-mention-service.test.ts
• New deps fixture in src/services/__tests__/cross-workspace-coupling-fence.test.ts

Recommended path to merge

1. Land experiment/phase2-combined-stack on main first (with whatever history-reconciliation strategy the team chooses for the unrelated-histories situation), OR re-target this PR to main and merge with --allow-unrelated-histories semantics.
2. Re-target PR feat(core): productize first-mention events + TLL EO read-path #17 base from experiment/phase2-combined-stack to main once (1) is resolved.
3. CI will auto-trigger on the re-target; gate on green build-and-test.
4. Run npm run migrate on production after merge (two new tables: temporal_linkage_list if not already migrated, first_mention_events).

Status

• PR remains DRAFT. Not flipped to Ready-for-Review by this audit.
• No code changes made by this audit; only this "Merge readiness" section was appended to the PR body.
• Untracked AGENTS.md left alone (project-context doc; mirrors the embedded CLAUDE.md content).