Disciplines · Decisions (ADRs)

ADR-0060: OSHUN Story-to-Source Journey Model

The PRD already states one of the most distinctive cross-domain moments OSHUN must support:

Accepted · 2026-03-24
9sections6 minread
Markdown source
On this page

Status: Accepted
Date: 2026-03-24
Authors: OSHUN Product, OSHUN Design, OSHUN Web Engineering
Reviewers: Veritas, Nisaba, Sophia leads
Supersedes: N/A
Superseded by: N/A

Context and Problem Statement#

The PRD already states one of the most distinctive cross-domain moments OSHUN must support:

A Veritas article should be able to show primary sources, lineage, related texts, and concept graphs through Nisaba and Sophia.

The codebase had many of the needed ingredients:

  • Veritas already had an article reader, claims view, source directory, and knowledge-graph route
  • Nisaba already had source, compare, notebook, and concept launch semantics
  • Sophia already had typed evidence packs, citation trails, notebooks, and graph previews

But there was no canonical shell-level answer to the question: "How does a story open into its sources?"

That gap mattered because story-to-source is not just another research feature. It is a trust behavior. The product should make it obvious that a Veritas story can be traced into citations, source lineage, related texts, and durable notes without dropping the original claim or story frame.

Decision Drivers#

  • Trust as a feature: Veritas stories should not terminate in summary alone.
  • Source inspectability: the source trail must stay attached to the exact story or claim the user is reading.
  • Cross-domain depth: Nisaba and Sophia should deepen Veritas rather than live as disconnected research tools.
  • Library durability: the journey should end in notebook or Library continuity, not a dead-end reader session.
  • Implementation leverage: Veritas reader, Nisaba launches, docs, and QA need one typed journey contract.

Considered Options#

Option 1: Leave story-to-source implicit in existing Veritas and Nisaba entry points#

Description: keep the current article reader, source directory, and Nisaba launch paths, but do not publish one canonical journey.

Pros:

  • Lowest implementation cost.
  • Reuses existing route depth without another model.

Cons:

  • Leaves the PRD requirement unowned.
  • Makes it easy for story reading and source reading to drift apart.
  • Gives QA and future mobile work no normative flow to reference.

Option 2: Treat story-to-source as a Veritas-only feature#

Description: keep the flow inside Veritas, with source and graph inspection never explicitly handing off into Nisaba or Library continuity.

Pros:

  • Simple to contain in one domain.
  • Fits a classic article-reader mental model.

Cons:

  • Violates the PRD requirement that lineage and related texts surface through Nisaba and Sophia.
  • Keeps current-events reading isolated from deeper textual scholarship.
  • Misses one of OSHUN’s clearest cross-domain moats.

Option 3: Publish an explicit story-to-source journey model and render it inside the Veritas reader (Chosen)#

Description: define one four-stage shell journey from story framing through source trail, lineage/text comparison, and durable preservation; publish it in shared navigation contracts; map it into contextual web actions; and render it inside the Veritas article reader.

Pros:

  • Makes the PRD story-to-source behavior executable.
  • Gives the Veritas reader a concrete handoff into Nisaba and Sophia-backed context.
  • Preserves the article frame while the user opens sources and notebook trails.
  • Produces one contract reusable by docs, web, QA, and later mobile work.

Cons:

  • Adds another cross-domain journey model that later work must respect.
  • Requires discipline so story-to-source remains distinct from research-to-practice and assistant-led continuity.

Decision Outcome#

Chosen option: Option 3.

Normative Rule#

OSHUN owns one canonical Story to source shell journey.

Its question is:

What sources, lineages, and related texts sit behind this story?

That journey is not complete when the user has merely read a story. It is complete when the shell has preserved a path from the article into inspectable evidence, source lineage, related texts, concept context, and a durable note or Library resume point.

Stage Rule#

The normative stage order is:

  1. Hold the story
  2. Open the source trail
  3. Trace lineage and texts
  4. Preserve the source arc

Stage Semantics#

1. Hold the story#

Veritas is the canonical entry surface for freezing the article into one bounded story frame and, when needed, one claim focus.

This stage exists to prevent source work from drifting away from the story the user actually opened.

2. Open the source trail#

Once the story frame is stable, the shell must expose:

  • Sophia-backed citation packs or source trails
  • Veritas evidence-chain or claim inspection

This stage is the trust pivot from summary into inspectable grounding.

3. Trace lineage and texts#

After the source trail is open, the shell must hand the user into Nisaba for:

  • source lineage
  • related texts or comparison
  • concept-graph direction when helpful through the Sophia-backed layer

This is where the story deepens from reporting into textual and conceptual context.

4. Preserve the source arc#

The journey must end in:

  • a Nisaba notebook or comparable study workspace
  • a Library resume point that preserves the article-to-source trail

This keeps the cross-domain investigation durable rather than session-bound.

Surface Rule#

  • Veritas is the canonical story-entry surface.
  • Sophia is the canonical grounding substrate for citations, evidence packs, and graph previews.
  • Nisaba is the canonical lineage and related-text surface.
  • Library is the canonical preserve surface for the completed source arc.

Contract Publication#

The shared story-to-source model lives in libs/oshun/navigation/src/story-source-journey.ts.

The web action mapping for that model lives in apps/oshun/web/src/navigation/story-source-journey.ts.

The current web rendering of that model lives in apps/oshun/web/src/components/domains/veritas/StorySourceJourneyRail.tsx.

Scope Boundaries#

  • This ADR defines the shell-level story-to-source journey, not a full Veritas source-management or Nisaba corpus-authoring system.
  • It does not replace the later sky-to-text or assistant-led continuity journey work.
  • It does not require a standalone Sophia customer route; Sophia remains a shared substrate surfaced through Veritas and Nisaba entry points in this slice.

Architecture Implications#

  • shared navigation code should expose typed story-to-source stages and handoffs
  • the Veritas reader should make the source trail explicit and actionable
  • Nisaba launches should preserve Veritas back-stack context so the story frame is not lost during the handoff
  • future mobile and assistant work can reuse one canonical story-to-source definition instead of inventing local copies

Acceptance Criteria#

V1-UX-008 is complete only when all criteria below are true:

  1. A canonical ADR defines the story-to-source journey model.
  2. Shared navigation code publishes the same stage and handoff model.
  3. The web Veritas reader reflects that model as actionable continuity guidance.
  4. The shipped model makes Veritas story framing, Sophia-backed source trails, Nisaba lineage/text comparison, and notebook preservation explicit.
  5. Tests verify the shared model, web action mapping, Veritas reader rendering, and cross-domain Nisaba handoff behavior.
  • docs/adr/ADR-0060-oshun-nisaba-first-class-customer-domain.md
  • docs/adr/ADR-0064-oshun-daypart-cross-domain-journey-model.md
  • docs/adr/ADR-0065-oshun-research-to-practice-journey-model.md

References#

  • docs/releases/v1/specs/web-app-admin-v1-prd.md
  • docs/releases/v1/reports/unified-product-gap-analysis-and-nisaba-integration-report-2026-03-22.md
  • libs/oshun/navigation/src/story-source-journey.ts
  • apps/oshun/web/src/navigation/story-source-journey.ts
  • apps/oshun/web/src/components/domains/veritas/StorySourceJourneyRail.tsx