Eve library

OSHUN V1 Canonical Contract Index and Query Requirements

Spec

Revision 1

On this page

Status: Active

Date: March 23, 2026

Owners: OSHUN Engineering, OSHUN Platform

Related:

  • docs/releases/v1/audits/cross-cutting/contract/to-prisma-alignment.md
  • libs/contracts/src/common/contract-prisma-alignment.ts
  • docs/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:

  1. Registry and discovery lists
  2. User-anchored continuation and library reads
  3. Governance and operations queues
  4. 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:

  • Collection
  • Concept
  • Notebook
  • Ritual
  • Practice
  • Source
  • VoiceProfile
  • AvatarPack
  • Persona
  • PolicyBundle
  • ModelCard
  • ModelVersion

Required patterns:

  • unique slug or key lookup for canonical deep links and admin edit routes
  • primaryDomain + status for 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, lastOpenedAt
  • Concept: primaryDomain + status, category + complexity, lastPublishedAt
  • Notebook: primaryDomain + status, visibility + status, lastOpenedAt
  • Ritual: primaryDomain + status, kind + status, lastPublishedAt
  • Practice: primaryDomain + status, kind + status, lastPublishedAt
  • Source: primaryDomain + status, type + credibilityTier, lastPublishedAt
  • VoiceProfile: status + approvalStatus, provider + providerVoiceId, publishedAt
  • AvatarPack: primaryDomain + status, status + approvalStatus, sortOrder
  • Persona: primaryDomain + status, status + approvalStatus, sortOrder
  • PolicyBundle: bundleKey, primaryDomain + status, category + scope + status, replacementBundleId
  • ModelCard: primaryDomain + status, modelId + version, modelVersionId
  • ModelVersion: primaryDomain + status, modelId + version, modelCardId

3.2 User-Anchored Continuation and Library Reads#

Applies to:

  • ContinuityState
  • ConsentRecord
  • MemoryScope
  • SupportCase
  • existing partial User, Project, Asset, Notification

Required patterns:

  • user or owner lookup index for the primary personalized fetch path
  • status + time indexes 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, lastActivityAt
  • ConsentRecord: primaryDomain + status, status + requestedAt, expiresAt, supersededById
  • MemoryScope: slug, primaryDomain + status, status + priority, isDefault
  • SupportCase: caseKey, primaryDomain + status, queue + priority + status, assignedToId + status

3.3 Governance and Operations Queues#

Applies to:

  • EvidencePack
  • ReviewPackage
  • Incident
  • ProvenanceBundle

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, notebookId
  • ReviewPackage: primaryDomain + status, artifactType + status, ownerId + status, dueAt
  • Incident: incidentKey, primaryDomain + status, queue + severity + status, detectedAt, resolvedAt
  • ProvenanceBundle: 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.ts
  • audit.ts
  • claim.ts
  • project.ts
  • user.ts
  • workflow-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, or caseKey, not by costly secondary filters.
  • Queue UIs should always combine status with priority, queue, ownerId, or dueAt rather 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.