Status: Active
Owner: OSHUN Studio Product Design + OSHUN Web
Last Updated: 2026-02-23
Related: docs/adr/ADR-0020-oshun-studio-navigation-and-command-surfaces.md
Purpose#
Define dependencies and canonical contracts for Studio navigation and command surface governance across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.
This document is the execution artifact for OST-00058.
Sources Used#
docs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/domains/bellona/features.mddocs/domains/yemaya/service-catalog.mddocs/domains/isis/service-catalog.mddocs/domains/hathor/service-catalog.mddocs/domains/aja/service-catalog.mddocs/domains/bellona/service-catalog.mddocs/releases/v1/design/ux-principles.mddocs/releases/v1/design/ergonomics-requirements.mdlibs/oshun/navigationapps/oshun/web/src/navigation/routes.tslibs/oshun/analytics
1. Dependency Overview#
1.1 Control Surfaces#
- Route contracts:
libs/oshun/navigation - Web route adapters:
apps/oshun/web/src/navigation - Command surface UI:
apps/oshun/web/src/components - Telemetry and audit:
libs/oshun/analytics+ Studio sinks
1.2 Domain Dependency Graph#
Navigation/Command Governance -> Yemaya: project and collaboration actions require predictable command scopes and return navigation.Navigation/Command Governance -> Isis: generation workflows require clear command history and context restoration.Navigation/Command Governance -> Hathor: narrative review flows require deterministic back-stack and command execution.Navigation/Command Governance -> Aja: timeline and animation tools require rapid command invocation with guarded high-impact actions.Navigation/Command Governance -> Bellona: build/runtime control surfaces require auditable command execution and fallback paths.Project Obsidian -> all: program-level governance for command and routing reliability.
2. Ownership and Contract Matrix#
| Area | Owner | Consumers | Artifact | Contract |
|---|---|---|---|---|
| Route contract schema | Navigation Platform | Web/mobile surfaces | Route registry | StudioRouteContract |
| Command catalog | Product Design + Web | Domain teams | Command registry | StudioCommandCatalog |
| Context restoration | Platform Web | Operators | Context payload | StudioNavigationContext |
| Command policy and approvals | Security + Product Ops | Engineering + QA | Policy map | CommandPolicyMatrix |
| Audit/telemetry stream | Data Platform | SRE + Governance | Event stream | NavigationCommandAuditEvent |
3. Canonical Contracts#
3.1 StudioRouteContract#
ts
export interface StudioRouteContract {
routeId: string;
path: string;
scope: 'global' | 'studio' | 'domain';
requiredContextKeys: string[];
supportsBackStack: boolean;
fallbackRoute: string;
}
3.2 StudioCommandCatalog#
ts
export interface StudioCommandCatalog {
catalogVersion: string;
commands: Array<{
commandId: string;
label: string;
scope: 'global' | 'workspace' | 'domain';
category: 'navigation' | 'execution' | 'review' | 'administration';
requiresConfirmation: boolean;
policyKey: string;
}>;
}
3.3 StudioNavigationContext#
ts
export interface StudioNavigationContext {
contextId: string;
programId: string;
projectId: string;
workspaceId: string;
originRoute: string;
backStack: string[];
persistedAt: string;
}
3.4 CommandPolicyMatrix#
ts
export interface CommandPolicyMatrix {
matrixId: string;
version: string;
policies: Array<{
policyKey: string;
allowedRoles: string[];
restrictedScopes: string[];
escalationPath: string;
}>;
}
3.5 NavigationCommandAuditEvent#
ts
export interface NavigationCommandAuditEvent {
eventId: string;
action:
| 'navigation.route.requested'
| 'navigation.route.completed'
| 'command.execute.requested'
| 'command.execute.completed'
| 'command.permission.denied';
outcome: 'allowed' | 'denied' | 'success' | 'error';
programId: string;
projectId: string;
workspaceId: string;
routeId: string;
commandId?: string;
role: string;
traceId: string;
occurredAt: string;
reason?: string;
}
4. Validation Rules#
- Production release blocked unless route and context-restoration checks pass.
- Production release blocked unless command policy matrix coverage is complete.
- All command executions require complete context and policy authorization.
- All allow/deny outcomes must emit
NavigationCommandAuditEventrecords.
5. Acceptance Criteria (OST-00058)#
OST-00058 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for routes, command catalog, context restoration, policy, and audit streams are documented.
- Ownership boundaries and validation rules are explicit.