query-point-reads / new pattern-ai-grounding-access: AI-grounding access pattern (point-read for known id)

[jaydestro]

#6 — Rubric Gap Analysis — new rule / enhancement: AI-grounding access pattern (point-read for known id)

Field	Value
Type	New Rule (preferred) or enhancement to query-point-reads
Target Rule	New pattern-ai-grounding-access under the pattern- category, OR new AI-grounding sub-section in query-point-reads
Severity	HIGH
Source	SCOPE Node.js AI Food Delivery — Scenario-specific criterion s_4_ai_access_pattern, Phase 3 static
Labels	SCOPE, enhancement, agent-kit, rule:query

Summary

In AI-grounded workloads, an LLM + tool-use loop typically resolves a concrete entity id (orderId, sessionId, documentId) from the user turn and then calls Cosmos DB to fetch the document-plus-events bundle to ground the model. Agents consistently emit SELECT * FROM c WHERE c.orderId = @orderId here — even when both id and partition key are known. The underlying fix is query-point-reads; what's missing is the AI-grounding idiom as a named pattern so the rule is discoverable from the LLM-plus-data-layer context where it applies.

Rubric Gap Analysis

s_4_ai_access_pattern hit-rate by cohort (HIT = grounding fetch uses point-read or PK-scoped query, not a generic cross-partition query):

Cohort	Hits	Misses	Hit rate
AK	4	21	16% (4/25)
Control	0	40	0% (0/40)
All	4	61	6.2% (4/65)

HIT runs (all four under AK profiles): P04/R01, P04/R03, P04/R04, P09/R02. Zero control-profile hits — cleanest cohort separation in this evaluation.

Pattern is recognizable statically: AI/LLM client import in the same file, function prepares messages or tool-call argument parsing, calls Cosmos DB with a single-id equality filter.

Evidence

Missing Anti-Pattern (typical grounding handler in Node.js runs)

export async function groundOrderContext(orderId: string, userId: string) {
  // ❌ Generic query — id is already known from the user turn / tool call
  const { resources: orderRows } = await ordersContainer.items.query<Order>({
    query: 'SELECT * FROM c WHERE c.orderId = @o',
    parameters: [{ name: '@o', value: orderId }],
  }).fetchAll();

  const { resources: events } = await eventsContainer.items.query<DeliveryEvent>({
    query: 'SELECT * FROM c WHERE c.orderId = @o ORDER BY c.timestamp DESC',
    parameters: [{ name: '@o', value: orderId }],
  }).fetchAll();

  return buildGroundingContext(orderRows[0], events);
}

Correct Pattern

export async function groundOrderContext(orderId: string, userId: string) {
  // ✅ Point read for the order (id + partition key both known)
  const orderResp = await ordersContainer.item(orderId, userId).read<Order>();
  const order = orderResp.resource;
  if (!order) return null;

  // ✅ PK-scoped projection for the event list (bounded by /orderId)
  const { resources: events } = await eventsContainer.items
    .query<DeliveryEvent>({
      query: 'SELECT c.id, c.orderId, c.timestamp, c.status, c.note FROM c WHERE c.orderId = @o ORDER BY c.timestamp DESC',
      parameters: [{ name: '@o', value: orderId }],
    }, { partitionKey: orderId })   // key fix: partition-scoped
    .fetchAll();

  return buildGroundingContext(order, events);
}

Why This Matters for AI Workloads

1. Grounding is latency-sensitive; each tool call adds to perceived response time.
2. Grounding is throughput-sensitive; a hot conversation drives the same partition key repeatedly — cross-partition fan-out hot-spots a single logical partition fastest.
3. The LLM tool-use loop hands the agent an id by construction. The rule needs to teach agents to recognize that signal and reach for the point read.

Implementation Options

Option A — enhance query-point-reads with an "AI grounding / RAG retrieval" sub-section covering:

• Typical signatures (function groundX(id, ...), tool-call handler, retrieval step).
• Static tell-tales (LLM client import, message assembly, tool-argument parsing).
• Before/after code pair.

Option B — new rule pattern-ai-grounding-access under the pattern- category (currently 3 rules). Cross-links to query-point-reads, query-use-projections, monitoring-ru-consumption.

A is lower-friction; B is more discoverable for skills layered on agent-framework / foundry evaluations. Preference: B — this pattern is cross-cutting and deserves its own rule name for tooling/scanning.

Rule Contradiction Scan

Rule	Interaction
query-point-reads	Underlying — new text is a usage pattern on top
query-use-projections (#1 draft)	Reinforcing — the preferred snippet uses a projection on the events query
query-avoid-cross-partition	Reinforcing — the anti-pattern violates this too (no partitionKey option)
pattern-* (existing 3 rules)	Category fit

No contradictions.

Documentation Cross-reference

• Not yet covered in Cosmos DB docs. Grounding / RAG guidance lives in Microsoft Foundry / Semantic Kernel / AI Search docs, not under Cosmos DB. This is explicitly a docs gap.
• Request Units — point reads cost fewer RUs than queries supplies the underlying cost argument.

Recommended cosmosdb-agent-kit Fix

1. Pick option A or B (preference: B).
2. Add the anti-pattern → correct-pattern block above.
3. Add static tell-tales so scanners can recognize the shape.
4. Cross-link to query-point-reads, query-use-projections, monitoring-ru-consumption.

[sajeetharan]

Agreed — this is a valid enhancement.