Examples (L2)

Scenario 1 — Batch ingest and retrieval

Ingest:

{
  "project_id": "proj_123",
  "items": [
    { "l1_document_id": "doc_1", "fragment": "#p3", "score_hint": 0.92 },
    { "l1_document_id": "doc_2" }
  ],
  "sync_cursor": "opaque"
}

Retrieve:

{
  "project_id": "proj_123",
  "query": "vector database recall",
  "top_k": 6,
  "time_ms": 8
}

Response (truncated):

{
  "items": [
    { "id": "l2_42", "score": 0.81, "reason": "entity match", "l1_ref": "doc_1#p3", "freshness": "hot" }
  ],
  "stats": { "t_ms": 3 }
}

Scenario 2 — Degradation under time budget

• Request time_ms = 4 → L2 reduces top_k and skips vector stage; returns metadata-only items

Scenario 3 — Idempotent upsert with conflict

• Same (project_id, l1_document_id, fragment) ingested twice → skipped: 1 and stable cursor

Scenario 4 — Eviction and freshness

• Items with recency_days > 90 and zero usage get evicted; events library.item.deprecated are emitted

Edge cases

• Missing fragment anchors after L1 rewrite → mark reference stale and re-index
• Large batch ingestion → throttle and chunk to respect budgets
• ACL changes in L1 → L2 hides items (no hard delete) until ACL resolved

Observability snippets

Expected log fields: request_id, project_id, top_k, t_ms, degradation_stage.

Example log line:

{
  "level": "info",
  "event": "l2.retrieve",
  "request_id": "req_abc",
  "project_id": "proj_123",
  "top_k": 6,
  "t_ms": 3,
  "degradation_stage": 0
}

See ./interfaces.md for API details and ../evaluation/ for L8 integration.