Status: Active
Date: March 23, 2026
Owners: OSHUN Engineering, OSHUN Platform
Related:
docs/releases/v1/audits/cross-cutting/contract/to-prisma-alignment.mdlibs/contracts/src/common/contract-prisma-alignment.tsdocs/releases/v1/specs/todos.md
1. Purpose#
This document defines the minimum index and query-shape requirements for canonical contract objects that serve high-traffic consumer or admin read paths.
The goal is not to index every field. The goal is to guarantee that the common read paths behind shell home, search, library, activity, governance queues, and admin review surfaces do not degrade into full-table scans as canonical contracts move into direct persistence.
2. Query Classes#
The canonical contract objects fall into four query classes:
- Registry and discovery lists
- User-anchored continuation and library reads
- Governance and operations queues
- Versioned artifact and release-governance lookups
Each class requires a predictable index baseline.
3. Required Index Patterns#
3.1 Registry and Discovery Lists#
Applies to:
CollectionConceptNotebookRitualPracticeSourceVoiceProfileAvatarPackPersonaPolicyBundleModelCardModelVersion
Required patterns:
- unique slug or key lookup for canonical deep links and admin edit routes
primaryDomain + statusfor domain-scoped browse queries- publication or recency timestamp index where the object is surfaced by latest or published order
- sort-order index where operator-curated registries or pickers depend on manual ordering
- object-specific identity pair indexes where versioned or provider-backed
records are queried by
(modelId, version)or(provider, providerVoiceId)
Implemented in this task block:
Collection:primaryDomain + status,visibility + status,lastOpenedAtConcept:primaryDomain + status,category + complexity,lastPublishedAtNotebook:primaryDomain + status,visibility + status,lastOpenedAtRitual:primaryDomain + status,kind + status,lastPublishedAtPractice:primaryDomain + status,kind + status,lastPublishedAtSource:primaryDomain + status,type + credibilityTier,lastPublishedAtVoiceProfile:status + approvalStatus,provider + providerVoiceId,publishedAtAvatarPack:primaryDomain + status,status + approvalStatus,sortOrderPersona:primaryDomain + status,status + approvalStatus,sortOrderPolicyBundle:bundleKey,primaryDomain + status,category + scope + status,replacementBundleIdModelCard:primaryDomain + status,modelId + version,modelVersionIdModelVersion:primaryDomain + status,modelId + version,modelCardId
3.2 User-Anchored Continuation and Library Reads#
Applies to:
ContinuityStateConsentRecordMemoryScopeSupportCase- existing partial
User,Project,Asset,Notification
Required patterns:
- user or owner lookup index for the primary personalized fetch path
status + timeindexes for “current”, “expiring”, or “needs attention” slices- due/expiry indexes where reminders, expirations, or renewal prompts drive UI
- assigned-owner indexes for shared queue views
Implemented in this task block:
ContinuityState:userId,primaryDomain + status,status + lastComputedAt,lastActivityAtConsentRecord:primaryDomain + status,status + requestedAt,expiresAt,supersededByIdMemoryScope:slug,primaryDomain + status,status + priority,isDefaultSupportCase:caseKey,primaryDomain + status,queue + priority + status,assignedToId + status
3.3 Governance and Operations Queues#
Applies to:
EvidencePackReviewPackageIncidentProvenanceBundle
Required patterns:
- status-first queue lookup
- priority, queue, artifact type, or subject type secondary filters
- due or resolution timestamps for SLA and stale-work detection
- owner/assignee indexes for queue partitioning and dashboards
Implemented in this task block:
EvidencePack:primaryDomain + status,kind + status,notebookIdReviewPackage:primaryDomain + status,artifactType + status,ownerId + status,dueAtIncident:incidentKey,primaryDomain + status,queue + severity + status,detectedAt,resolvedAtProvenanceBundle:primaryDomain + status,subjectType + status,publishedAt
3.4 Passage and Scholarly Retrieval#
Applies to:
Passage
Required patterns:
- status-filtered browse
- publication ordering for editorial and study surfaces
- visibility-filtered list access
Implemented in this task block:
Passage:primaryDomain + status,visibility + status,lastPublishedAt
4. Partial-Mapping Requirements#
For the six partial mappings still anchored in legacy owner schemas, the current read-path requirement is:
- do not remove or weaken the existing indexes those domains already rely on
- prefer additive indexes when the canonical read path becomes hot
- do not declare the canonical contract “direct” until the full read shape is queryable without adapter-only aggregate synthesis
This currently applies to:
asset.tsaudit.tsclaim.tsproject.tsuser.tsworkflow-template.ts
5. Query-Pattern Guardrails#
- Consumer list routes should default to
status-filtered reads, not unbounded scans over draft or archived records. - Shell and admin deep links should resolve primarily by canonical
slug,bundleKey,incidentKey, orcaseKey, not by costly secondary filters. - Queue UIs should always combine
statuswithpriority,queue,ownerId, ordueAtrather than sorting the whole table in memory. - Versioned artifacts should resolve by stable identity pairs such as
(modelId, version)before falling back to generic search. - JSON-heavy canonical models should keep hot filter fields as top-level scalar columns; nested JSON should be used for shape preservation, not for primary queue filtering.
6. Enforcement#
These requirements are enforced indirectly by:
- the authoritative mapping manifest in
libs/contracts/src/common/contract-prisma-alignment.ts - direct owner-schema indexes added in the Prisma schemas touched by this task block
- migration/rollback diff tests in
libs/contracts/src/common/contract-prisma-migrations.test.ts
Future performance work should add explain-plan and load-test coverage where a canonical object moves from low-frequency admin use to launch-critical consumer traffic.