Phase 6: publish stable consumption seams for research and SDK consumers

[ethanj]

Summary

Phase 6 of the rearchitecture — publishes the composition root built in Phases 1A–1B as a stable consumption surface. Research harnesses, the extension, and SDK consumers can now boot core through three documented seams (HTTP, in-process runtime container, docker/E2E compose) instead of re-building a parallel runtime.

The work in this repo is narrow on purpose: publish the seams, prove they work in a contract test, document the boundary. The actual migration of research harnesses onto these seams lives in atomicmemory-research, tracked separately.

What changed

Public API (src/index.ts)

• Adds createCoreRuntime + types (CoreRuntime, CoreRuntimeDeps, CoreRuntimeConfig, CoreRuntimeRepos, CoreRuntimeServices, CoreRuntimeConfigRouteAdapter)
• Adds createApp, checkEmbeddingDimensions + EmbeddingDimensionCheckResult, bindEphemeral + BootedApp
• Existing exports preserved — current research paths keep working (Risk 4: avoid breaking research in the same step that gives it a new seam)

Seam promotion

• src/__tests__/test-helpers.ts → src/app/bind-ephemeral.ts so research can import the canonical HTTP-boot helper without reaching into a test dir. JSDoc refreshed. Two importers updated.

Contract test (src/app/__tests__/research-consumption-seams.test.ts)

• In-process seam: runtime.services.memory.ingest / .search end-to-end

• HTTP seam: POST /memories/ingest + /memories/search via bindEphemeral

• Parity, both directions:

  1. in-process write → HTTP search sees the IDs
  2. HTTP write → in-process search sees the IDs

  Two-directional parity is the requirement because direction (1) alone would miss a regression where POST /memories/ingest transforms or validates the request body differently from runtime.services.memory.ingest(...). Direction (2) is what pins the HTTP ingest contract to the in-process contract.

Docs

• docs/consuming-core.md — new. HTTP / in-process / docker seams, copy-pastable examples using the literal package.json#name (@atomicmemory/atomicmemory-engine), stability boundary for deep-path imports, what belongs in research vs. core.
• docs/README.md + CLAUDE.md — pointers to the new doc.

Out of scope (explicit)

• No research-repo changes — migrating harnesses is follow-up work there.
• No narrowing of ./services/* / ./db/* deep-path exports in package.json — Risk 4 again; deprecate in docs now, remove once research has migrated.
• No config split (Phase 1B/2) or retrieval decomposition (Phase 3). Phase 6 publishes only the seams Phases 1A–1B already built.

Test plan

• npx tsc --noEmit — clean
• npm test — 957/957 pass (was 953 pre-Phase-6; +4 contract tests)
• fallow --no-cache — 0 above threshold, maintainability 90.9 (good)
• Existing composed-boot-parity.test.ts still passes after the import-path update
• Existing memory-route-config-seam.test.ts still passes after the import-path update
• CI green on the branch
• Optional sanity: npm run test:docker-smoke still green (no compose files changed — regression check only, not a new requirement)

🤖 Generated with Claude Code