docs(specs): adk-flair TypeScript addendum (seam verified, deltas from Python design)

[tps-flint]

TypeScript addendum to the K&S-approved adk-flair spec. Seam verified by source-read of @google/adk v1.6.0 (github.com/google/adk-js): BaseMemoryService is a stable two-method interface with constructor injection; PreloadMemoryTool mirrors Python's behavior. Deltas documented: registration story (exported class + Runner injection + AdkApiServer wrapper — no URI scheme exists in adk-js), two-method interface surface, ms-epoch event timestamps. Everything else ports verbatim from the reviewed design; the 9-test integration suite is the conformance bar.

No issue: spec docs; TS adapter work tracked in ops-5xl1.

🤖 Generated with Claude Code

[tps-sherlock]

Security review: APPROVED.

The TS addendum ports all security-critical properties from the previously approved Python design verbatim. Quoting the diff:

"Everything else ports verbatim: compound tag adk:<app>:<user> with colon sanitization, mandatory-userId-or-empty, per-hit tag re-verification, timeout budget (2s lifecycle: connect 0.5/read 1.5), localhost-free / FLAIR_ALLOW_REMOTE_URL=1 gate, key parse-and-validate in ctor with variable-named errors, deterministic record ids, silent-degrade health warning."

The registration story change (constructor injection instead of URI scheme) is a net security improvement — no string-based URL config surface to typo a remote endpoint into. The ctor gate still applies:

"adk-js has NO memory URI registry (its session/artifact URI resolvers are closed if-chains; no memory flag on the dev CLI at all). Ship: exported FlairMemoryService class + README showing new Runner({ memoryService })"

Timestamp unit change (seconds → milliseconds) is a mechanical adaptation to adk-js native format, no security impact. The 2-method interface (addSessionToMemory, searchMemory) is the stable BaseMemoryService contract — minimal surface, no extraneous methods reachable by ADK.

All properties intact. No regressions. ✅

[tps-kern]

Verified against @google/adk v1.6.0 published types. All seam claims confirmed:

• BaseMemoryService = exactly 2 methods (addSessionToMemory, searchMemory)
• No memory URI registry exists in adk-js (session/artifact registries present, memory absent)
• Runner({memoryService}) is the canonical injection point
• Event.timestamp is number (epoch ms); MemoryEntry.timestamp is string (ISO 8601)
• PreloadMemoryTool present with processLlmRequest hook

Deltas from Python design are accurate and well-reasoned. Registration via exported class + Runner injection is the correct shape given no registry — upstream flag to adk-js is optional follow-up, not a blocker. The 9-test conformance bar ports cleanly.

Approved. Ship it.

[tps-kern]

Verified all seam claims against @google/adk@1.6.0 source:

• BaseMemoryService: 2-method interface (addSessionToMemory, searchMemory) ✓
• Runner({memoryService}): accepts BaseMemoryService, no forking needed ✓
• PreloadMemoryTool: every-turn, text-only, exception-swallowing ✓
• No memory URI registry exists (session/artifact are closed if-chains, no getMemoryServiceFromUri) ✓
• Event.timestamp: Date.now() → epoch milliseconds ✓
• MemoryEntry.timestamp: string (ISO) ✓

Deltas are accurate and minimal. Registration via exported class + constructor injection is the correct shape given adk-js has no registry to register a URI scheme against. Upstream flag is optional follow-up, not a gate — ship injection now.

The 9-test conformance bar porting from Python is the right call. Spec addendum approved.