Authored by Claude Opus 4.7 (Claude Code). Session cff20948-2dbb-4ac4-99e2-df2ebe967a4b.

Resolves #10017 (under the intake-reshape prescription approved by @tobiu this session — see the ticket's reshape note for the full rationale).

Summary

Pins the multi-tenant migration design decision (lazy-tag-on-read, zero back-fill) as the source of truth for #10010 / #10011 downstream work, ships the operator-facing healthcheck.migration.untaggedCount observability surface, and adds a regression guard for the write-side "every write requires a bound agent identity" invariant that the migration strategy depends on.

This PR is the narrow design-anchor of the #10017 reshape — the larger retrieval-flag plumbing (#10010, Gemini's track) and SQLite RLS (#10011, Gemini's track) consume this doc as their reference.

Intake-reshape context

The original #10017 (Apr-14) prescribed a back-fill migration script that would assign userId: 'default' to all untagged ChromaDB rows. That prescription predated the post-#10144 graph-first identity substrate. After cross-family A2A design alignment with @neo-gemini-pro this session, both of us converged on lazy-tag-on-read as the architecturally-correct primitive for the post-substrate-elevation world. @tobiu approved the reshape on the ticket.

Four concrete arguments against back-fill (full detail in the MultiTenantMigrationGuide.md §Core Decision and the ticket's reshape note):

1. Locks a default-tenant identity into historical data forever
2. Non-idempotent under concurrent writes racing with #10145-wrapped dispatches
3. Destroys pre-tenant-aware-era provenance (the semantic truth of legacy rows)
4. Doesn't scale to real multi-user deployments where tenant data is orders of magnitude larger than current ~10k memories

Scope Walkthrough

Net delta: +344 / -0. Zero deletions. One conditional new-field addition to healthcheck payload (migration is additive; doesn't change existing fields).

Test Evidence

$ npm run test-unit -- test/playwright/unit/ai/mcp/server/memory-core/services/WriteSideInvariant.spec.mjs
3 passed (805ms)

$ npm run test-unit -- test/playwright/unit/ai/mcp/server/memory-core/services/HealthService.spec.mjs
6 passed (904ms)

$ npm run test-unit -- test/playwright/unit/ai/mcp/server/memory-core/services/MailboxService.spec.mjs
27 passed (1.1s)

All specs pass individually. Pre-existing Playwright fullyParallel worker interleaving flakiness between specs when combined in a single invocation is orthogonal to this PR.

Empirical Validation

Healthcheck from fresh mcp-client spawn against dev:

"migration": {
  "memory":  0,
  "session": 0,
  "total":   0,
  "available": true
}

Zero counts on current dev (no MEMORY/SESSION graph nodes yet; ingestion-pending state is correctly surfaced as available: true, total: 0). When operators run real multi-user workloads post-upgrade, the counts will reflect untagged-legacy-surface-area shrinking over time as natural query patterns move writes toward 100% tagged coverage.

Design Decisions

Why not ship memorySharing flag implementation here? Out of scope per the reshape. The flag's plumbing (MCP tool schema + retrieval filter logic) is #10010's ownership (Gemini's track). This PR pins the design enum + semantics; Gemini's PR consumes the doc and ships the code. Clean separation of concerns.

Why MailboxService.addMessage as the write-side invariant exemplar? It's the enforcement site that already codifies the pattern (line ~89-92 checks getAgentIdentityNodeId() and throws loudly on null). Pinning the exemplar as regression coverage protects the discipline. If MemoryService.addMemory or SessionService don't yet enforce the same pattern, that's a separate ticket — the migration guide names it as follow-up gap territory.

Why SQLite aggregation instead of ChromaDB filter? ChromaDB's query semantics make "missing-field" hard to express directly. SQLite graph nodes are the canonical tenant-identity substrate post-#10144; aggregating there matches the AUTHORED_BY / OWNED_BY edge topology. COALESCE(json_extract(..., '$.properties.userId'), '') = '' treats both NULL and empty-string as untagged uniformly.

Why available: false state for pre-init healthchecks? Honest signaling. Substrate-readiness is separate from migration health; conflating them in a "zero count" would falsely claim post-migration state when the reality is pre-init. Follows the same discipline as #10176's identity-block {source: 'unresolved', bound: false, nodeId: null} projection.

Cross-family Coordination

Sent heads-up to @neo-gemini-pro via A2A mailbox (MESSAGE:fb7c3729-5a5c-43a0-9b48-94d03ae62ab1) flagging the doc-as-source-of-truth approach + confirming zero file overlap with her #10010 / #10011 work. She's parallel-tracking on agent/10245-docs-empirical-isolation + agent/10256-fix-permission-spec right now (seen on fetch); her #10011 will consume the design this PR pins.

Parallel coordination note

Fetch confirms multiple in-flight Gemini branches:

• agent/10245-docs-empirical-isolation
• agent/10256-fix-permission-spec

Zero file overlap with this PR.

Cross-family Review

Requesting review from @neo-gemini-pro per pull-request §6.1 mandate. Her review lens on:

1. Whether the memorySharing enum + semantics pinned here match what #10010's tool-schema implementation needs
2. Whether the "legacy rows never retroactively tagged" invariant works cleanly with #10011's planned RLS policy
3. The write-side invariant exemplar — any gaps in MemoryService / SessionService write paths that warrant a follow-up ticket

Handoff

Per pull-request §6.2 (Human-in-the-Loop), halting for @tobiu's PR-level review + cross-family review from @neo-gemini-pro. Post-merge: the doc becomes the design anchor for Gemini's #10010 / #10011 PRs; they reference it as the semantic source of truth.