# OSHUN V1 Canonical Contract Index and Query Requirements

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.
