git.stella-ops.org/docs/modules/ui/search-chip-context-contract.md

Search Chip Context Contract

Purpose

• Define one deterministic contract for page-aware search chips.
• Let feature teams add page suggestions without editing AmbientContextService logic.
• Blend route context, last few page actions, and bounded suggestion randomization.

Rule (mandatory for page teams)

• Every page that needs custom search chips must declare a context entry in SEARCH_CONTEXT_DEFINITIONS.
• Page components should implement SearchContextComponent with searchContextId so ownership is explicit.
• Context definitions must provide:
  • id
  • routePrefixes
  • optional domain
  • optional searchSuggestions[]
  • optional chatSuggestions[]
  • optional chatRoutePattern
• Suggestion arrays must stay deterministic and bounded:
  • at most 3 base chips per page context
  • short, action-oriented text
  • no tenant/user secrets in fallback text

Source of truth

• Contract and registry:
  • src/Web/StellaOps.Web/src/app/core/services/search-context.registry.ts
• Runtime composition:
  • src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts

Runtime behavior

• Base chips come from the page context array.
• A deterministic rotation (session + route scope + 5-minute bucket) varies chip order.
• Last few actions for the current page scope are tracked (bounded history, TTL 15 minutes).
• Up to 2 follow up: ... chips are generated from recent actions and prioritized above base chips.
• One strategic chip is generated from dominant/recent action intent.

Page ownership workflow

1. Add/adjust a context in SEARCH_CONTEXT_DEFINITIONS.
2. Ensure page component exposes the same searchContextId (implements SearchContextComponent).
3. Add/adjust unit tests in ambient-context.service.spec.ts.
4. Add/adjust Playwright tests for route chips + action-driven chips.

Non-goals

• No unbounded per-page suggestion memory.
• No runtime remote fetch for chip definitions.
• No randomization based on Math.random() (must remain replayable).