title: L2 Data Models description: Entities, schemas, and indexes for Project Library (L2). priority: 0.72 lastmod: 2025-09-06

L2 Data Models

• Reference — points to an L1 document/fragment; minimal metadata only

  • id: string (l2_<id>)
  • project_id: string
  • l1_document_id: string
  • fragment: string (optional anchor/offset)
  • features: object (scoring features, e.g., entity hits)
  • freshness: "hot" | "warm" | "cold"
  • pinned: boolean
  • created_at: string (ISO8601), updated_at: string (ISO8601)

• CurationIndex — precomputed features to support ranking and hotset management

  • reference_id: string (FK → Reference.id)
  • score_hint: number (0..1)
  • recency_days: number
  • entity_overlap: number
  • source_reliability: number

JSON examples

Reference (result item):

{
	"id": "l2_42",
	"project_id": "proj_123",
	"l1_document_id": "doc_1",
	"fragment": "#p3",
	"features": { "entities": ["VectorDB"], "entity_overlap": 0.8 },
	"freshness": "hot",
	"pinned": true,
	"created_at": "2025-09-01T10:00:00Z",
	"updated_at": "2025-09-06T09:00:00Z"
}

Indexes

• (project_id, l1_document_id, fragment) unique — deduplication
• (project_id, freshness, pinned) — hotset maintenance
• (project_id, score_hint DESC, recency_days ASC) — retrieval prefilter
• Vector index (optional) over embedding of title+summary from L1

Retention & lifecycle

• Pin golden items; compress low-signal; evict stale by recency_days and usage
• Track provenance: source repo/commit, ingestion cursor

Constraints

• No raw PII duplication in Reference
• Fragment anchors must be stable across L1 revisions (or re-indexed)